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.

You can also import via the REST API. Both paths use the same conversion service and produce identical content output. The main differences:

Choose the REST API if you need server-side processing, access to footnote or endnote data, or raw unfiltered JSON.

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 the complete list of extensions, configuration, and what each one handles, see the ConvertKit page.

Required extensions

Install ConvertKit — it bundles every extension the importer needs: the standard nodes and marks, TextStyleKit for color/font/size/line-height/background, TextAlign preconfigured for ['paragraph', 'heading'], Highlight with multicolor: true, an Image with DOCX crop attributes, ConvertTableKit for DOCX-aware tables, and PageBreak:

import { ConvertKit } from '@tiptap-pro/extension-convert-kit'

new Editor({ extensions: [ConvertKit] })

You can disable any individual slot via ConvertKit.configure({ slot: false }) if you need to swap one of the bundled extensions for your own (e.g. when pairing with the Pages extension, set table: false and register TableKit from @tiptap-pro/extension-pages-tablekit instead). See the ConvertKit reference for the full slot list.

Configure

Add the Import extension to your editor setup.

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

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

Image upload configuration

The imageUploadConfig option lets you configure how the conversion service uploads images found in the DOCX file to your server. This replaces the deprecated imageUploadCallbackUrl string option and gives you full control over headers, HTTP method, and query parameters.

ImportDocx.configure({
  appId: 'your-app-id',
  token: 'your-jwt',
  imageUploadConfig: {
    url: 'https://your-server.com/upload-image',
    headers: {
      Authorization: 'Bearer your-upload-token',
      'X-Custom-Header': 'custom-value',
    },
    method: 'PUT',
    queryParams: {
      bucket: 'images',
      folder: 'docx-imports',
    },
  },
})

// Before (deprecated)
ImportDocx.configure({
  imageUploadCallbackUrl: 'https://your-server.com/upload-image',
})

// After
ImportDocx.configure({
  imageUploadConfig: {
    url: 'https://your-server.com/upload-image',
  },
})

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 importDocx command. Here it replaces the current editor content with the converted content and focuses the editor:

editor.chain().focus().importDocx({ 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()
  .importDocx({
    file,
    onImport(context) {
      // Discriminated union: handle the failure branch first.
      if (context.error) {
        showErrorToast({ message: context.error.message })
        return
      }

      const { setEditorContent, content } = context

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

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

      // Insert the (possibly modified) content. Pass it to the context-provided
      // `setEditorContent` function, which does the right wiring around it
      // (including auto-applying headers/footers when Pages is registered).
      setEditorContent(content)
    },
  })
  .focus()
  .run()

Operations that we have controlled in the example above:

Headers & Footers

When importing a .docx file that contains headers and footers, the import extension automatically detects and applies them if the Pages extension is installed. Without Pages, the header/footer data is still returned to your onImport callback (see Manual handling below) but has nowhere to render — install Pages to make them visible in the editor.

Automatic handling

If the Pages extension is registered in your editor, headers and footers are applied automatically when you call setEditorContent():

editor
  .chain()
  .importDocx({
    file,
    onImport(context) {
      if (context.error) {
        console.error(context.error)
        return
      }

      // Headers and footers are applied automatically alongside the body content
      context.setEditorContent()
    },
  })
  .focus()
  .run()

If the Pages extension is not installed, the header and footer data is still available in the onImport callback but is not automatically applied to the editor.

Manual handling

The onImport callback provides all header and footer fields for manual processing:

editor
  .chain()
  .importDocx({
    file,
    onImport(context) {
      if (context.error) {
        console.error(context.error)
        return
      }

      // Access header/footer data directly
      const {
        header, // Default header (Tiptap JSON or null)
        footer, // Default footer (Tiptap JSON or null)
        headerFirstPage, // First page header (Tiptap JSON or null)
        footerFirstPage, // First page footer (Tiptap JSON or null)
        headerOdd, // Odd page header (Tiptap JSON or null)
        footerOdd, // Odd page footer (Tiptap JSON or null)
        headerEven, // Even page header (Tiptap JSON or null)
        footerEven, // Even page footer (Tiptap JSON or null)
      } = context

      // Set body content without automatic header/footer application
      editor.commands.setContent(context.content)

      // Manually apply headers and footers via Pages extension commands
      if (header) editor.commands.setHeader(header)
      if (footer) editor.commands.setFooter(footer)

      if (headerFirstPage || footerFirstPage) {
        editor.commands.setDifferentFirstPage(true)
        if (headerFirstPage) editor.commands.setHeaderFirstPage(headerFirstPage)
        if (footerFirstPage) editor.commands.setFooterFirstPage(footerFirstPage)
      }

      if (headerOdd || headerEven || footerOdd || footerEven) {
        editor.commands.setDifferentOddEven(true)
        if (headerOdd) editor.commands.setHeaderOdd(headerOdd)
        if (headerEven) editor.commands.setHeaderEven(headerEven)
        if (footerOdd) editor.commands.setFooterOdd(footerOdd)
        if (footerEven) editor.commands.setFooterEven(footerEven)
      }
    },
  })
  .focus()
  .run()

Available fields

Footnotes & Endnotes

The import API can extract footnote and endnote content from DOCX files. Inline references in the document body are represented as footnoteReference and endnoteReference nodes, each with a noteId attribute. However, these nodes require a custom extension to render in the editor.

Verbose output

The DOCX import extension provides a verbose configuration property to help you control the level of diagnostic output during the import process. This is especially useful for debugging or for getting more insight into what happens during conversion.

The verbose property is a bitmask number that determines which types of log messages are emitted. The extension uses the following levels:

The verbose output will give you, along the data property, one more property called logs, which will contain info, warn, and error properties, each of them being an array with all of the information related to that specific verbosity.

{
  "data": {
    "content": {
        // Tiptap JSON
    }
  },
  "logs": {
    "info": [],
    "warn": [
      {
        "message": "Image file not found in media files",
        "fileName": "image1.gif",
        "availableMediaFiles": []
      }
    ],
    "error": [
      {
        "message": "Image upload failed: General error",
        "fileName": "image1.gif",
        "url": "https://your-image-upload-endpoint.com",
        "error": "Unable to connect. Is the computer able to access the url?",
        "context": "uploadImage general error"
      }
    ]
  }
}

Support & Limitations

For a detailed breakdown of which document features are supported at each stage of the pipeline, see the Supported features matrix.