---
title: "Image Upload Button"
description: "Add a button that uploads and inserts an image into your Tiptap editor. More in the documentation!"
canonical_url: "https://tiptap.dev/docs/ui-components/components/image-upload-button"
---

# Image Upload Button

Add a button that uploads and inserts an image into your Tiptap editor. More in the documentation!

A fully accessible image upload button for Tiptap editors. Easily insert images with keyboard shortcut support and flexible customization options.

> **Interactive demo:** [image upload button](https://template.tiptap.dev/preview/tiptap-ui/image-upload-button)

## Installation

Add the component via the Tiptap CLI:

```bash
npx @tiptap/cli@latest add image-upload-button
```

## Components

### `<ImageUploadButton />`

A prebuilt React component that inserts images into the editor.

#### Usage

```tsx
import { EditorContent, EditorContext, useEditor } from '@tiptap/react'
import { StarterKit } from '@tiptap/starter-kit'
import { Image } from '@tiptap/extension-image'
import { ImageUploadButton } from '@/components/tiptap-ui/image-upload-button'
import { ImageUploadNode } from '@/components/tiptap-node/image-upload-node'
import { handleImageUpload, MAX_FILE_SIZE } from '@/lib/tiptap-utils'

import '@/components/tiptap-node/image-node/image-node.scss'
import '@/components/tiptap-node/paragraph-node/paragraph-node.scss'

export default function MyEditor() {
  const editor = useEditor({
    immediatelyRender: false,
    extensions: [
      StarterKit,
      Image,
      ImageUploadNode.configure({
        accept: 'image/*',
        maxSize: MAX_FILE_SIZE,
        limit: 3,
        upload: handleImageUpload,
        onError: (error) => console.error('Upload failed:', error),
      }),
    ],
    content: `
        <p>Click the button to upload an image.</p>
        `,
  })

  return (
    <EditorContext.Provider value={{ editor }}>
      <ImageUploadButton
        editor={editor}
        text="Add Image"
        hideWhenUnavailable={true}
        showShortcut={true}
        onInserted={() => console.log('Image inserted!')}
      />

      <EditorContent editor={editor} role="presentation" />
    </EditorContext.Provider>
  )
}
```

#### Props

| Name                  | Type             | Default     | Description                                            |
| --------------------- | ---------------- | ----------- | ------------------------------------------------------ |
| `editor`              | `Editor \| null` | `undefined` | The Tiptap editor instance                             |
| `text`                | `string`         | `undefined` | Optional text label for the button                     |
| `hideWhenUnavailable` | `boolean`        | `false`     | Hides the button when image insertion is not available |
| `onInserted`          | `() => void`     | `undefined` | Callback fired after a successful image insertion      |
| `showShortcut`        | `boolean`        | `false`     | Shows a keyboard shortcut badge (if available)         |

## Hooks

### `useImageUpload()`

A custom hook to build your own image upload button with full control over rendering and behavior.

#### Usage

```tsx
function MyImageUploadButton() {
  const { isVisible, isActive, canInsert, handleImage, label, shortcutKeys, Icon } = useImageUpload(
    {
      editor: myEditor,
      hideWhenUnavailable: true,
      onInserted: () => console.log('Image inserted!'),
    },
  )

  if (!isVisible) return null

  return (
    <button onClick={handleImage} disabled={!canInsert} aria-label={label} aria-pressed={isActive}>
      <Icon />
      {label}
      {shortcutKeys && <Badge>{parseShortcutKeys({ shortcutKeys })}</Badge>}
    </button>
  )
}
```

#### Props

| Name                  | Type             | Default     | Description                                          |
| --------------------- | ---------------- | ----------- | ---------------------------------------------------- |
| `editor`              | `Editor \| null` | `undefined` | The Tiptap editor instance                           |
| `hideWhenUnavailable` | `boolean`        | `false`     | Hides the button if image insertion is not available |
| `onInserted`          | `() => void`     | `undefined` | Callback fired after a successful image insertion    |

#### Return Values

| Name           | Type            | Description                                |
| -------------- | --------------- | ------------------------------------------ |
| `isVisible`    | `boolean`       | Whether the button should be rendered      |
| `isActive`     | `boolean`       | If an image is currently selected          |
| `canInsert`    | `boolean`       | If image insertion is currently allowed    |
| `handleImage`  | `() => boolean` | Function to insert an image                |
| `label`        | `string`        | Accessible label text for the button       |
| `shortcutKeys` | `string`        | Keyboard shortcut (Cmd/Ctrl + Shift + I)   |
| `Icon`         | `React.FC`      | Icon component for the image upload button |

## Utilities

### `canInsertImage(editor)`

Checks if an image can be inserted in the current editor state.

```tsx
import { canInsertImage } from '@/components/tiptap-ui/image-upload-button'

const canInsert = canInsertImage(editor) // Check if image can be inserted
```

### `insertImage(editor)`

Programmatically inserts an image in the editor.

```tsx
import { insertImage } from '@/components/tiptap-ui/image-upload-button'

const success = insertImage(editor)
if (success) {
  console.log('Image inserted successfully!')
}
```

### `isImageActive(editor)`

Checks if an image is currently active/selected in the editor.

```tsx
import { isImageActive } from '@/components/tiptap-ui/image-upload-button'

const active = isImageActive(editor)
```

## Keyboard Shortcuts

The image upload button supports the following keyboard shortcut:

- **Cmd/Ctrl + Shift + I**: Insert an image

The shortcut is automatically registered when using either the `<ImageUploadButton />` component or the `useImageUpload()` hook.

## Requirements

### Dependencies

- `@tiptap/react` - Core Tiptap React integration
- `react-hotkeys-hook` - Keyboard shortcut management

### Referenced Components

- `use-tiptap-editor` (hook)
- `button` (primitive)
- `badge` (primitive)
- `tiptap-utils` (lib)
- `image-plus-icon` (icon)