Editor

The Editor class is the core of Tiptap. It manages the editor state, view, and provides the API for content manipulation.

Constructor

Create a new editor instance.

const editor = new Editor(options: Partial<EditorOptions>)

options · Partial<EditorOptions>

Configuration options for the editor.

Show properties

element · Element | { mount: HTMLElement } | ((editor: HTMLElement) => void) | null

The DOM element to mount the editor to. If null, the editor won’t be mounted automatically.

content · Content · default: "''"

The initial content of the editor (HTML, JSON, or a JSON array).

extensions · Extensions · default: "[]"

Array of Tiptap extensions to use.

editable · boolean · default: "true"

Whether the editor is editable.

autofocus · FocusPosition · default: "false"

The editor’s initial focus position. Can be true, false, 'start', 'end', a number, or 'all'.

injectCSS · boolean · default: "true"

Whether to inject base CSS styles.

injectNonce · string | undefined

A nonce to use for CSP while injecting styles.

textDirection · 'ltr' | 'rtl' | 'auto' | undefined

The default text direction for all content. When set, all nodes will have the corresponding dir attribute.

editorProps · EditorProps · default: "{}"

ProseMirror EditorProps to pass to the view.

parseOptions · ParseOptions · default: "{}"

Options for parsing content.

enableInputRules · EnableRules · default: "true"

Whether to enable input rules.

enablePasteRules · EnableRules · default: "true"

Whether to enable paste rules.

enableCoreExtensions · boolean | Partial<Record<CoreExtensionName, false>> · default: "true"

Whether to enable core extensions. Can be false to disable all, or an object to disable specific extensions.

enableContentCheck · boolean · default: "false"

If true, the editor will check content for errors on initialization.

onBeforeCreate · (props: { editor: Editor }) => void

Called before the editor is constructed.

onCreate · (props: { editor: Editor }) => void

Called after the editor is constructed.

onMount · (props: { editor: Editor }) => void

Called when the editor is mounted.

onUnmount · (props: { editor: Editor }) => void

Called when the editor is unmounted.

onUpdate · (props: { editor: Editor; transaction: Transaction }) => void

Called when the editor’s content is updated.

onSelectionUpdate · (props: { editor: Editor; transaction: Transaction }) => void

Called when the editor’s selection is updated.

onTransaction · (props: { editor: Editor; transaction: Transaction }) => void

Called after a transaction is applied.

onFocus · (props: { editor: Editor; event: FocusEvent; transaction: Transaction }) => void

Called on focus events.

onBlur · (props: { editor: Editor; event: FocusEvent; transaction: Transaction }) => void

Called on blur events.

onDestroy · () => void

Called when the editor is destroyed.

onContentError · (props: { editor: Editor; error: Error; disableCollaboration: () => void }) => void

Called when the editor encounters an error while parsing content.

Properties

schema

editor.schema: Schema

The ProseMirror schema used by the editor.

view

editor.view: EditorView

The ProseMirror EditorView instance.

state

editor.state: EditorState

The current ProseMirror EditorState.

commands

editor.commands: SingleCommands

An object of all registered commands. Each command returns a boolean indicating success.

storage

editor.storage: Storage

The editor storage object. Extensions can store data here.

isEditable

editor.isEditable: boolean

Whether the editor is currently editable.

isFocused

editor.isFocused: boolean

Whether the editor is currently focused.

isEmpty

editor.isEmpty: boolean

Whether the editor content is empty.

isDestroyed

editor.isDestroyed: boolean

Whether the editor has been destroyed.

isInitialized

editor.isInitialized: boolean

Whether the editor is initialized (after the create event has been emitted).

instanceId

editor.instanceId: string

A unique ID for this editor instance.

Methods

chain()

Create a command chain to call multiple commands at once.

editor.chain(): ChainedCommands

return · ChainedCommands

A chainable command object. End with .run() to execute.

Example

editor.chain().focus().toggleBold().run()

can()

Check if a command or command chain can be executed without actually executing it.

editor.can(): CanCommands

return · CanCommands

An object with the same commands as editor.commands, but they return true/false instead of executing.

Example

if (editor.can().toggleBold()) {
  // Bold can be toggled
}

setOptions()

Update editor options.

editor.setOptions(options: Partial<EditorOptions>): void

options · Partial<EditorOptions> · required

Options to update.

Example

editor.setOptions({
  editable: false,
  editorProps: {
    attributes: {
      class: 'readonly-editor',
    },
  },
})

setEditable()

Update the editable state of the editor.

editor.setEditable(editable: boolean, emitUpdate?: boolean): void

editable · boolean · required

Whether the editor should be editable.

emitUpdate · boolean · default: "true"

Whether to emit an update event.

Example

editor.setEditable(false)

mount()

Attach the editor to a DOM element.

editor.mount(element: Element): void

element · Element · required

The DOM element to mount the editor to.

Example

const editor = new Editor({ element: null })
editor.mount(document.querySelector('#editor'))

unmount()

Remove the editor from the DOM, but allow remounting later.

editor.unmount(): void

Example

editor.unmount()

destroy()

Destroy the editor instance and cleanup.

editor.destroy(): void

Example

editor.destroy()

getJSON()

Get the document as JSON.

editor.getJSON(): JSONContent

return · JSONContent

The editor content as a JSON object.

Example

const json = editor.getJSON()
console.log(json)
// { type: 'doc', content: [...] }

getHTML()

Get the document as HTML.

editor.getHTML(): string

return · string

The editor content as an HTML string.

Example

const html = editor.getHTML()
console.log(html)
// '<p>Hello world</p>'

getText()

Get the document as plain text.

editor.getText(options?: {
  blockSeparator?: string
  textSerializers?: Record<string, TextSerializer>
}): string

options · object

Show properties

blockSeparator · string · default: "'\\\\n\\\\n'"

The string to use between block nodes.

textSerializers · Record<string, TextSerializer> · default: "{}"

Custom text serializers for specific node types.

return · string

The editor content as plain text.

Example

const text = editor.getText()
console.log(text)
// 'Hello world'

const textWithCustomSeparator = editor.getText({ blockSeparator: ' ' })

getAttributes()

Get attributes of the currently selected node or mark.

editor.getAttributes(nameOrType: string | NodeType | MarkType): Record<string, any>

nameOrType · string | NodeType | MarkType · required

The name or type of the node or mark.

return · Record<string, any>

The attributes of the node or mark.

Example

const linkAttrs = editor.getAttributes('link')
console.log(linkAttrs.href)

isActive()

Check if a node or mark is active at the current selection.

editor.isActive(name: string, attributes?: Record<string, any>): boolean
editor.isActive(attributes: Record<string, any>): boolean

name · string

The name of the node or mark.

attributes · Record<string, any>

Optional attributes to match.

return · boolean

Whether the node or mark is active.

Example

if (editor.isActive('bold')) {
  console.log('Bold is active')
}

if (editor.isActive('link', { href: 'https://example.com' })) {
  console.log('Link with this href is active')
}

if (editor.isActive({ textAlign: 'center' })) {
  console.log('Text is centered')
}

registerPlugin()

Register a ProseMirror plugin.

editor.registerPlugin(
  plugin: Plugin,
  handlePlugins?: (newPlugin: Plugin, plugins: Plugin[]) => Plugin[]
): EditorState

plugin · Plugin · required

The ProseMirror plugin to register.

handlePlugins · (newPlugin: Plugin, plugins: Plugin[]) => Plugin[]

Optional function to control how the plugin is merged into existing plugins.

return · EditorState

The new editor state.

Example

import { Plugin } from '@tiptap/pm/state'

const customPlugin = new Plugin({
  // plugin configuration
})

editor.registerPlugin(customPlugin)

unregisterPlugin()

Unregister a ProseMirror plugin.

editor.unregisterPlugin(
  nameOrPluginKey: string | PluginKey | (string | PluginKey)[]
): EditorState | undefined

nameOrPluginKey · string | PluginKey | (string | PluginKey)[] · required

The plugin name or PluginKey to remove.

return · EditorState | undefined

The new editor state, or undefined if the plugin wasn’t found.

Example

editor.unregisterPlugin('myPlugin')

$node()

Query for a single node using a CSS-like selector.

editor.$node(selector: string, attributes?: Record<string, any>): NodePos | null

selector · string · required

A CSS-like selector (e.g., 'paragraph', 'heading[level=1]').

attributes · Record<string, any>

Additional attributes to match.

return · NodePos | null

A NodePos object if found, otherwise null.

Example

const heading = editor.$node('heading[level=1]')
if (heading) {
  console.log(heading.node.textContent)
}

$nodes()

Query for multiple nodes using a CSS-like selector.

editor.$nodes(selector: string, attributes?: Record<string, any>): NodePos[] | null

selector · string · required

A CSS-like selector.

attributes · Record<string, any>

Additional attributes to match.

return · NodePos[] | null

An array of NodePos objects if found, otherwise null.

Example

const paragraphs = editor.$nodes('paragraph')
paragraphs?.forEach(p => console.log(p.node.textContent))

$pos()

Get a resolved position at the given position.

editor.$pos(pos: number): NodePos

pos · number · required

The position in the document.

return · NodePos

A NodePos object for the given position.

Example

const nodePos = editor.$pos(10)

$doc

Get a NodePos for the document root.

editor.$doc: NodePos

Example

const docNode = editor.$doc
console.log(docNode.node.childCount)

Events

The editor extends EventEmitter and emits the following events:

beforeCreate

Emitted before the editor is created.

editor.on('beforeCreate', ({ editor }) => {
  console.log('Before create', editor)
})

create

Emitted when the editor is ready.

editor.on('create', ({ editor }) => {
  console.log('Editor is ready', editor)
})

mount

Emitted when the editor is mounted.

editor.on('mount', ({ editor }) => {
  console.log('Editor mounted', editor)
})

unmount

Emitted when the editor is unmounted.

editor.on('unmount', ({ editor }) => {
  console.log('Editor unmounted', editor)
})

update

Emitted when the content changes.

editor.on('update', ({ editor, transaction }) => {
  console.log('Content updated', editor, transaction)
})

selectionUpdate

Emitted when the selection changes.

editor.on('selectionUpdate', ({ editor, transaction }) => {
  console.log('Selection updated', editor, transaction)
})

transaction

Emitted after each transaction.

editor.on('transaction', ({ editor, transaction }) => {
  console.log('Transaction', editor, transaction)
})

focus

Emitted when the editor gains focus.

editor.on('focus', ({ editor, event, transaction }) => {
  console.log('Editor focused', editor, event)
})

blur

Emitted when the editor loses focus.

editor.on('blur', ({ editor, event, transaction }) => {
  console.log('Editor blurred', editor, event)
})

destroy

Emitted when the editor is destroyed.

editor.on('destroy', () => {
  console.log('Editor destroyed')
})

contentError

Emitted when there’s an error parsing content.

editor.on('contentError', ({ editor, error, disableCollaboration }) => {
  console.error('Content error', error)
})

Example

import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'

const editor = new Editor({
  element: document.querySelector('#editor'),
  extensions: [StarterKit],
  content: '<p>Hello World!</p>',
  onUpdate: ({ editor }) => {
    console.log('Content updated:', editor.getHTML())
  },
})

// Use commands
editor.chain().focus().toggleBold().run()

// Get content
const html = editor.getHTML()
const json = editor.getJSON()

// Check state
if (editor.isActive('bold')) {
  console.log('Bold is active')
}

// Cleanup
editor.destroy()