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 integrationreact-hotkeys-hook
- Keyboard shortcut management
Referenced Components
use-tiptap-editor
(hook)button
(primitive)badge
(primitive)tiptap-utils
(lib)image-plus-icon
(icon)