Skip to main content
The Image extension allows you to insert images into your document. It supports both inline and block-level images, with optional resizing capabilities.

​
Installation

npm install @tiptap/extension-image

​
Usage

import { Editor } from '@tiptap/core'
import Document from '@tiptap/extension-document'
import Image from '@tiptap/extension-image'
import Paragraph from '@tiptap/extension-paragraph'
import Text from '@tiptap/extension-text'

const editor = new Editor({
  extensions: [
    Document,
    Paragraph,
    Text,
    Image,
  ],
})

​
Configuration

​
inline

Controls whether the image node should be inline or block-level.
​
inline
boolean
default:"false"
When true, images are rendered as inline elements that flow with text.
Image.configure({
  inline: true,
})

​
allowBase64

Controls whether base64 images are allowed.
​
allowBase64
boolean
default:"false"
Enable this to allow base64-encoded image URLs in the src attribute.
Image.configure({
  allowBase64: true,
})

​
HTMLAttributes

Custom HTML attributes to add to the image element.
​
HTMLAttributes
Record<string, any>
default:"{}"
Custom HTML attributes that should be added to the rendered HTML tag.
Image.configure({
  HTMLAttributes: {
    class: 'my-image',
  },
})

​
resize

Controls if the image should be resizable.
​
resize
object | false
default:"false"
Enable image resizing with optional configuration for directions, minimum dimensions, and aspect ratio preservation.
Image.configure({
  resize: {
    enabled: true,
    directions: ['top', 'right', 'bottom', 'left', 'topLeft', 'topRight', 'bottomLeft', 'bottomRight'],
    minWidth: 100,
    minHeight: 100,
    alwaysPreserveAspectRatio: true,
  },
})

​
Attributes

The Image node supports the following attributes:
  • src: The image URL (required)
  • alt: Alternative text for the image
  • title: Title text for the image
  • width: Image width in pixels
  • height: Image height in pixels

​
Commands

​
setImage

Inserts an image with the specified attributes. 
editor.commands.setImage({
  src: 'https://example.com/image.jpg',
  alt: 'A description of the image',
  title: 'Image title',
})

// With dimensions
editor.commands.setImage({
  src: 'https://example.com/image.jpg',
  alt: 'A description',
  width: 500,
  height: 300,
})

​
Input Rules

The Image extension supports Markdown-style input rules:
  • Type ![alt text](url) to insert an image
  • Type ![alt text](url "title") to insert an image with a title

​
Examples

​
Basic Image

editor.commands.setImage({
  src: 'https://tiptap.dev/logo.png',
  alt: 'Tiptap Logo',
})

​
Inline Images

const editor = new Editor({
  extensions: [
    // other extensions...
    Image.configure({
      inline: true,
    }),
  ],
})

​
Resizable Images

const editor = new Editor({
  extensions: [
    // other extensions...
    Image.configure({
      resize: {
        enabled: true,
        minWidth: 100,
        minHeight: 100,
      },
    }),
  ],
})

​
Allow Base64 Images

const editor = new Editor({
  extensions: [
    // other extensions...
    Image.configure({
      allowBase64: true,
    }),
  ],
})

editor.commands.setImage({
  src: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
  alt: 'A tiny image',
})

​
Draggable

Images are draggable by default, allowing users to move them within the document.

​
Source Code

View the source code on GitHub: packages/extension-image/src/image.ts

Build docs developers (and LLMs) love

Get started for freeTalk to us