Skip to main content

​
Overview

The useEditor hook is the primary way to create and manage a Tiptap editor instance in React applications. It handles the editor lifecycle, including creation, updates, and cleanup.

​
Type Signature

function useEditor(
  options: UseEditorOptions,
  deps?: DependencyList
): Editor | null

​
Parameters

​
options
UseEditorOptions
required
Configuration options for the editor instance. Extends Partial<EditorOptions> from @tiptap/core.
​
deps
DependencyList
default:"[]"
Optional React dependency array. When dependencies change, the editor instance will be destroyed and recreated.

​
Return Value

Returns an Editor instance or null. The return value can be null when:
  • The editor has not been initialized yet
  • immediatelyRender is set to false and the editor hasn’t mounted
  • Server-side rendering is detected

​
Usage Examples

​
Basic Usage

import { useEditor, EditorContent } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'

function MyEditor() {
  const editor = useEditor({
    extensions: [StarterKit],
    content: '<p>Hello World!</p>',
  })

  return <EditorContent editor={editor} />
}

​
With Event Handlers

import { useEditor, EditorContent } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'
import { useState } from 'react'

function MyEditor() {
  const [status, setStatus] = useState('initializing')

  const editor = useEditor({
    extensions: [StarterKit],
    content: '<p>Hello World!</p>',
    onCreate: () => {
      setStatus('created')
    },
    onUpdate: ({ editor }) => {
      console.log('Content updated:', editor.getHTML())
    },
    onFocus: () => {
      setStatus('focused')
    },
    onBlur: () => {
      setStatus('blurred')
    },
  })

  return (
    <div>
      <p>Editor status: {status}</p>
      <EditorContent editor={editor} />
    </div>
  )
}

​
With Dependencies

import { useEditor, EditorContent } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'

function MyEditor({ initialContent }: { initialContent: string }) {
  const editor = useEditor({
    extensions: [StarterKit],
    content: initialContent,
  }, [initialContent]) // Recreate editor when initialContent changes

  return <EditorContent editor={editor} />
}

​
Server-Side Rendering

import { useEditor, EditorContent } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'

function MyEditor() {
  const editor = useEditor({
    extensions: [StarterKit],
    content: '<p>Hello World!</p>',
    immediatelyRender: false, // Required for SSR
  })

  if (!editor) {
    return <div>Loading editor...</div>
  }

  return <EditorContent editor={editor} />
}

​
Controlled Editor

import { useEditor, EditorContent } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'
import { useEffect, useState } from 'react'

function MyEditor() {
  const [content, setContent] = useState('<p>Hello World!</p>')

  const editor = useEditor({
    extensions: [StarterKit],
    content,
    onUpdate: ({ editor }) => {
      setContent(editor.getHTML())
    },
  })

  // Update editor when external content changes
  useEffect(() => {
    if (editor && editor.getHTML() !== content) {
      editor.commands.setContent(content)
    }
  }, [content, editor])

  return (
    <div>
      <EditorContent editor={editor} />
      <textarea
        value={content}
        onChange={(e) => setContent(e.target.value)}
      />
    </div>
  )
}

​
Important Notes

When using server-side rendering (SSR) with frameworks like Next.js, you must set immediatelyRender: false to avoid hydration mismatches. In development mode, Tiptap will throw an error if SSR is detected without this option.
The shouldRerenderOnTransaction option is legacy behavior. For better performance, leave it as false (default) and use the useEditorState hook for reactive state updates instead.
Use the deps array sparingly. Only include dependencies when you actually need to recreate the editor instance. For most use cases, updating editor options or content through commands is more efficient.

Build docs developers (and LLMs) love

Get started for freeTalk to us