Image Upload Button

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

Installation

Add the component via the Tiptap CLI:

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

Components

`<ImageUploadButton />`

A prebuilt React component that inserts images into the editor.

Usage

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

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.

import { canInsertImage } from '@/registry/tiptap-ui/image-upload-button'

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

`insertImage(editor)`

Programmatically inserts an image in the editor.

import { insertImage } from '@/registry/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.

import { isImageActive } from '@/registry/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)