Import .docx in your editor

Converting .docx files to Tiptap JSON is simple with the @tiptap-pro/extension-import-docx editor extension, which integrates directly into your Tiptap Editor.

If you need to import .docx content outside the Editor, use the REST API.

Install the DOCX Import extension

The Conversion extensions are published in Tiptap’s private npm registry. Integrate the extensions by following the private registry guide.

Install the Tiptap Import extension package:

npm i @tiptap-pro/extension-import-docx

Ensure your editor includes all necessary Tiptap extensions to handle content from DOCX. For example, include the Image extension for inline images, and the Table extension for tables.

Required extensions

In order to fully map DOCX content (e.g. images, tables, styled text) onto Tiptap’s schema, you must include the relevant Tiptap extensions. Without these extensions, certain DOCX elements may not be recognized or properly rendered by the editor.

import StarterKit from '@tiptap/starter-kit'
import Color from '@tiptap/extension-color'
import FontFamily from '@tiptap/extension-font-family'
import Highlight from '@tiptap/extension-highlight'
import { Image } from '@tiptap/extension-image'
import Link from '@tiptap/extension-link'
import Paragraph from '@tiptap/extension-paragraph'
import Table from '@tiptap/extension-table'
import TableCell from '@tiptap/extension-table-cell'
import TableHeader from '@tiptap/extension-table-header'
import TableRow from '@tiptap/extension-table-row'
import TextAlign from '@tiptap/extension-text-align'
import TextStyle from '@tiptap/extension-text-style'
import Underline from '@tiptap/extension-underline'

Configure

Add the Import extension to your editor setup.

// Import the Import extension
import { Import } from '@tiptap-pro/extension-import-docx'

const editor = new Editor({
  extensions: [
    // Other extensions ...
    Import.configure({
      appId: 'your-app-id', // Your Convert App ID (see Tiptap Cloud settings)
      token: 'your-jwt-token', // JWT for authentication (see Authentication documentation)
      imageUploadCallbackUrl: 'https://your-image-upload-endpoint.com', // Your upload images endpoint
    })
    // Other extensions ...
  ],
  // Other editor settings ...
})

Import a DOCX file

Once the extension is configured, you can import a DOCX file selected by the user.

Basic import

The simplest approach is to pass the file directly to the import command. Here it replaces the current editor content with the converted content and focuses the editor:

editor.chain().focus().import({ file }).run()

In most cases, this one-liner is all you need to let users import .docx files. The extension handles sending the file to the conversion endpoint, retrieving the converted Tiptap JSON, and inserting it into the editor.

Import handling

In order to have more control after the import process have finished, you would use the onImport callback to handle the conversion result. This callback provides the converted content, any errors that occurred, and a function called setEditorContent to insert the content from context.content into the editor. If you don't provide an onImport callback, the extension will automatically insert the content into the editor but you won't be able to handle anything else like errors or loading states.

editor
  .chain()
  .import({
    file,
    onImport(context) {
      const { setEditorContent, content, error } = context

      // Add error handling
      if (error) {
        showErrorToast({ message: error.message })
      }

      // You could also modify the content before inserting it
      content.doc.content.push({ type: 'paragraph', content: [{ type: 'text', text: 'Hello!' }] })

      // You can change the loading state of your application for example
      isLoading = false

      // Perform the insertion in the editor
      editor.commands.setEditorContent(content)
    },
  })
  .focus()
  .run()

Operations that we have controlled in the example above:

Support & Limitations

Importing .docx files into Tiptap provides a way to handle most standard Word content, but it’s not a one-to-one mapping due to inherent differences between DOCX formatting and Tiptap’s CSS-based styles.

Currently supported features and known limitations: