Extensions

Extensions are the building blocks of Tiptap. Learn how to use and create extensions to add functionality to your editor.

Extensions are the modular building blocks of Tiptap. Every feature in Tiptap is packaged as an extension, whether it’s a node (like paragraphs or headings), a mark (like bold or italic), or functionality (like history or placeholder).

What are Extensions?

Tiptap has three types of extensions:

Extensions

Generic extensions that add functionality without defining content structure (e.g., StarterKit, Placeholder, CharacterCount)

Nodes

Block or inline content types that make up your document (e.g., Paragraph, Heading, Image)

Marks

Formatting that can be applied to text (e.g., Bold, Italic, Link)

All three types share the same underlying Extendable base class and can be used interchangeably in the extensions array.

Using Extensions

Extensions are passed to the editor via the extensions option:

import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { Bold } from '@tiptap/extension-bold'
import { Italic } from '@tiptap/extension-italic'

const editor = new Editor({
  extensions: [
    StarterKit,
    Bold,
    Italic,
  ],
})

Configuring Extensions

Most extensions accept options that can be configured using the configure() method:

import { Editor } from '@tiptap/core'
import { Heading } from '@tiptap/extension-heading'
import { Link } from '@tiptap/extension-link'

const editor = new Editor({
  extensions: [
    Heading.configure({
      levels: [1, 2, 3], // Only allow h1, h2, h3
      HTMLAttributes: {
        class: 'my-heading',
      },
    }),
    Link.configure({
      openOnClick: false,
      HTMLAttributes: {
        class: 'my-link',
        rel: 'noopener noreferrer',
      },
    }),
  ],
})

Extension Structure

Every extension is created using the Extension.create(), Node.create(), or Mark.create() static methods:

import { Extension } from '@tiptap/core'

export const MyExtension = Extension.create({
  name: 'myExtension',
  
  addOptions() {
    return {
      // Default options
      myOption: 'default value',
    }
  },
  
  addCommands() {
    return {
      myCommand: () => ({ commands }) => {
        // Command implementation
        return true
      },
    }
  },
  
  addKeyboardShortcuts() {
    return {
      'Mod-k': () => this.editor.commands.myCommand(),
    }
  },
  
  // More hooks...
})

Source: /home/daytona/workspace/source/packages/core/src/Extension.ts:23

Extension API

Configuration

name · string · required

The unique name of the extension. This is used to identify the extension.

name: 'myExtension'

priority · number · default: "100"

The priority determines the order in which extensions are loaded. Higher priority extensions are loaded first.

priority: 1000

addOptions · () => Options

Define default options for your extension.

addOptions() {
  return {
    HTMLAttributes: {},
    openOnClick: true,
  }
}

addStorage · () => Storage

Define storage that persists across the lifetime of the editor.

addStorage() {
  return {
    count: 0,
    users: [],
  }
}

Access storage via editor.storage.extensionName:

editor.storage.myExtension.count

Commands

addCommands · () => Commands

Add commands that can be called via editor.commands.

addCommands() {
  return {
    setAwesome: () => ({ commands }) => {
      return commands.insertContent('<p>Awesome!</p>')
    },
  }
}

Usage:

editor.commands.setAwesome()

Keyboard Shortcuts

addKeyboardShortcuts · () => Record<string, () => boolean>

Add keyboard shortcuts for your extension.

addKeyboardShortcuts() {
  return {
    'Mod-b': () => this.editor.commands.toggleBold(),
    'Mod-Shift-x': () => this.editor.commands.myCommand(),
  }
}

Mod is Cmd on Mac and Ctrl on Windows/Linux.

Input Rules

addInputRules · () => InputRule[]

Add input rules for markdown-style shortcuts.

addInputRules() {
  return [
    markInputRule({
      find: /(?:^|\s)(\*\*(?!\s+\*\*)((?:[^*]+))\*\*)$/,
      type: this.type,
    }),
  ]
}

This would convert **text** to bold text as you type.

Paste Rules

addPasteRules · () => PasteRule[]

Add paste rules for handling pasted content.

addPasteRules() {
  return [
    markPasteRule({
      find: /(?:^|\s)(\*\*(?!\s+\*\*)((?:[^*]+))\*\*)/g,
      type: this.type,
    }),
  ]
}

ProseMirror Plugins

addProseMirrorPlugins · () => Plugin[]

Add ProseMirror plugins to extend functionality.

addProseMirrorPlugins() {
  return [
    new Plugin({
      key: new PluginKey('myPlugin'),
      // Plugin configuration
    }),
  ]
}

Global Attributes

addGlobalAttributes · () => GlobalAttribute[]

Add attributes to multiple node or mark types.

addGlobalAttributes() {
  return [
    {
      types: ['heading', 'paragraph'],
      attributes: {
        textAlign: {
          default: 'left',
          renderHTML: attributes => ({
            style: `text-align: ${attributes.textAlign}`,
          }),
          parseHTML: element => element.style.textAlign || 'left',
        },
      },
    },
  ]
}

Lifecycle Hooks

onCreate · () => void

Called when the editor is created.

onCreate() {
  console.log('Extension initialized')
}

onUpdate · () => void

Called when the editor content changes.

onUpdate() {
  this.storage.count++
}

onSelectionUpdate · () => void

Called when the selection changes.

onTransaction · ({ transaction }) => void

Called for every transaction.

onFocus · ({ event }) => void

Called when the editor receives focus.

onBlur · ({ event }) => void

Called when the editor loses focus.

onDestroy · () => void

Called when the editor is destroyed. Use this to clean up resources.

onDestroy() {
  // Clean up event listeners, timers, etc.
}

Creating an Extension

Here’s a complete example of a custom extension:

import { Extension } from '@tiptap/core'
import { Plugin, PluginKey } from '@tiptap/pm/state'

export interface CharacterCountOptions {
  limit: number | null
}

export const CharacterCount = Extension.create<CharacterCountOptions>({
  name: 'characterCount',
  
  addOptions() {
    return {
      limit: null,
    }
  },
  
  addStorage() {
    return {
      characters: () => {
        return this.editor.state.doc.textContent.length
      },
      words: () => {
        return this.editor.state.doc.textContent.split(/\s+/).filter(Boolean).length
      },
    }
  },
  
  onCreate() {
    console.log(`Character limit: ${this.options.limit}`)
  },
  
  onUpdate() {
    const count = this.storage.characters()
    
    if (this.options.limit && count > this.options.limit) {
      console.warn('Character limit exceeded!')
    }
  },
  
  addProseMirrorPlugins() {
    return [
      new Plugin({
        key: new PluginKey('characterCount'),
        // Plugin logic
      }),
    ]
  },
})

Usage

const editor = new Editor({
  extensions: [
    CharacterCount.configure({
      limit: 1000,
    }),
  ],
})

// Access storage
const count = editor.storage.characterCount.characters()
const words = editor.storage.characterCount.words()

Extending Extensions

You can extend existing extensions to modify or add functionality:

import { Paragraph } from '@tiptap/extension-paragraph'

const CustomParagraph = Paragraph.extend({
  addAttributes() {
    return {
      ...this.parent?.(),
      textAlign: {
        default: 'left',
        renderHTML: attributes => ({
          style: `text-align: ${attributes.textAlign}`,
        }),
        parseHTML: element => element.style.textAlign || 'left',
      },
    }
  },
})

The this.parent?.() call merges the parent extension’s attributes with your new ones.

Extension Packages

Tiptap provides many official extensions:

Starter Kit

import StarterKit from '@tiptap/starter-kit'

const editor = new Editor({
  extensions: [
    StarterKit,
  ],
})

The StarterKit includes:

• Document
• Paragraph
• Text
• Bold
• Italic
• Strike
• Code
• Heading
• Blockquote
• BulletList
• OrderedList
• ListItem
• CodeBlock
• HardBreak
• HorizontalRule
• History
• Dropcursor
• Gapcursor

Individual Extensions

import { Bold } from '@tiptap/extension-bold'
import { Italic } from '@tiptap/extension-italic'
import { Underline } from '@tiptap/extension-underline'
import { Link } from '@tiptap/extension-link'
import { Image } from '@tiptap/extension-image'
import { Table } from '@tiptap/extension-table'
import { TableRow } from '@tiptap/extension-table-row'
import { TableCell } from '@tiptap/extension-table-cell'
import { Placeholder } from '@tiptap/extension-placeholder'
import { CharacterCount } from '@tiptap/extension-character-count'

Real-World Example: Bold Extension

Here’s the actual implementation of the Bold extension from the Tiptap source:

import { Mark, markInputRule, markPasteRule, mergeAttributes } from '@tiptap/core'

export interface BoldOptions {
  HTMLAttributes: Record<string, any>
}

declare module '@tiptap/core' {
  interface Commands<ReturnType> {
    bold: {
      setBold: () => ReturnType
      toggleBold: () => ReturnType
      unsetBold: () => ReturnType
    }
  }
}

const starInputRegex = /(?:^|\s)(\*\*(?!\s+\*\*)((?:[^*]+))\*\*(?!\s+\*\*))$/
const starPasteRegex = /(?:^|\s)(\*\*(?!\s+\*\*)((?:[^*]+))\*\*(?!\s+\*\*))/g

export const Bold = Mark.create<BoldOptions>({
  name: 'bold',
  
  addOptions() {
    return {
      HTMLAttributes: {},
    }
  },
  
  parseHTML() {
    return [
      { tag: 'strong' },
      { tag: 'b', getAttrs: node => (node as HTMLElement).style.fontWeight !== 'normal' && null },
      { style: 'font-weight', getAttrs: value => /^(bold(er)?|[5-9]\d{2,})$/.test(value as string) && null },
    ]
  },
  
  renderHTML({ HTMLAttributes }) {
    return ['strong', mergeAttributes(this.options.HTMLAttributes, HTMLAttributes), 0]
  },
  
  addCommands() {
    return {
      setBold: () => ({ commands }) => commands.setMark(this.name),
      toggleBold: () => ({ commands }) => commands.toggleMark(this.name),
      unsetBold: () => ({ commands }) => commands.unsetMark(this.name),
    }
  },
  
  addKeyboardShortcuts() {
    return {
      'Mod-b': () => this.editor.commands.toggleBold(),
      'Mod-B': () => this.editor.commands.toggleBold(),
    }
  },
  
  addInputRules() {
    return [
      markInputRule({ find: starInputRegex, type: this.type }),
    ]
  },
  
  addPasteRules() {
    return [
      markPasteRule({ find: starPasteRegex, type: this.type }),
    ]
  },
})

Source: /home/daytona/workspace/source/packages/extension-bold/src/bold.tsx:56

TypeScript Support

import { Extension } from '@tiptap/core'
import type { Editor } from '@tiptap/core'

interface MyOptions {
  color: string
  size: number
}

interface MyStorage {
  count: number
}

export const MyExtension = Extension.create<MyOptions, MyStorage>({
  name: 'myExtension',
  
  addOptions() {
    return {
      color: 'blue',
      size: 12,
    }
  },
  
  addStorage() {
    return {
      count: 0,
    }
  },
})

Best Practices

Unique Names

Always use unique extension names to avoid conflicts.

name: 'myCompany_myExtension'

Clean Up Resources

Use onDestroy to clean up event listeners, timers, and other resources.

onDestroy() {
  this.observer?.disconnect()
  clearInterval(this.timer)
}

Use TypeScript

Define types for your options and storage for better developer experience.

Test Thoroughly

Extensions can interact in unexpected ways. Test your extension with various combinations of other extensions.

Related

Nodes & Marks

Learn about creating node and mark extensions

Commands

Learn about the command system

Schema

Learn about how extensions generate the schema

Editor

Learn about the Editor class