Image

Insert and manage images with support for resizing and base64 encoding.

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

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