Legacy DOCX Import & Export

The original extension-import and extension-export packages for Tiptap provide reliable methods to import and export DOCX files.

These extensions, and associated endpoints remain available to anyone with a Tiptap account but are deprecated and no longer actively developed.

They have been replaced by the new Tiptap Conversion extensions and services.

The following guide focuses on configuring the legacy extensions.

Import legacy extension

// Start with importing the extension
import { Import } from '@tiptap-pro/extension-import'

const editor = new Editor({
  // ...
  extensions: [
    // ...
    Import.configure({
      // The Convert App-ID from the Convert settings page: https://cloud.tiptap.dev/convert-settings
      appId: 'your-app-id',

      // The JWT you generated in the previous step
      token: 'your-jwt',

      // The URL to upload images to, if not provided, images will be stripped from the document
      imageUploadCallbackUrl: 'https://your-image-upload-url.com',

      // Enables the experimental DOCX import which should better preserve content styling
      experimentalDocxImport: true,
    }),
  ],
})

Import your first document

// The most simple way to import a file
// This will import the uploaded file, replace the editor content
// and focus the editor
editor.chain().focus().import({ file }).run()

Customize the import behavior

// You can also use the onImport callback to customize the import behavior
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

      // make sure you call the setEditorContent function if you want to run
      // the default insertion behavior of the extension
      // setEditorContent()
      // but since we modified the content, we need to do the insertion manually
      editor.commands.setContent(content)
    },
  })
  .focus()
  .run()

Import options

Commands

import

Arguments

Supported formats

• docx - Microsoft Word, Google Docs, OpenOffice, LibreOffice and others
• odt - OpenDocument Text format used by OpenOffice, LibreOffice and others
• rtf - Rich Text Format used by Microsoft Word, Google Docs and others
• Commonmark markdown - Markdown format used by various editors and platforms
• GFM markdown - GitHub Flavored Markdown used by GitHub

Caveats and limitations

• Image upload - Images are assumed to be inline within the document so, your editor should be setup with Image.configure({ inline: true }) to display them correctly, otherwise they will be stripped from the document
• Unsupported docx elements on import - Importing docx files currently does not support page breaks, page headers and footers, horizontal rules or text styles
• Content added via suggestion mode - Content added via suggestion mode is not included in the imported ProseMirror document
• PDF import & export - Importing and exporting PDF files is not yet supported
• Inline styles - Inline styles are currently not parsed and are not available in import & export

Export legacy extension

// Start with importing the extension
import { Export } from '@tiptap-pro/extension-export'

const editor = new Editor({
  // ...
  extensions: [
    // ...
    Export.configure({
      // The Convert App-ID from the convert settings page: https://cloud.tiptap.dev/convert-settings
      appId: 'your-app-id',

      // The JWT you generated in the previous step
      token: 'your-jwt',
    }),
  ],
})

Export a document

// Do a simple export to docx
// Supported formats: docx, odt, md and gfm
editor.chain().focus().export({ format: 'docx' }).run()

Customize the export behavior

// You can also use the onExport callback to customize the export behavior
editor.chain().export({
  format: 'docx',
  onExport(context) {
    const { blob, error, download, filename } = context

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

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

    // you could modify the filename or handle the blob differently here
    // but we will keep them as they are

    // you can trigger a download directly by calling the download method
    download()

    // keep in mind that the download method will only work in the browser
    // and if the blob and filename was changed before must be managed manually
  },
})

Export options

Commands

export

Arguments

Supported formats

• docx - Microsoft Word, Google Docs, OpenOffice, LibreOffice and others
• odt - OpenDocument Text format used by OpenOffice, LibreOffice and others
• Commonmark markdown - Markdown format used by various editors and platforms
• GFM markdown - GitHub Flavored Markdown used by GitHub

Caveats and limitations

• Custom Node exports - Exporting custom nodes or marks is supported in the new Conversion extensions and endpoints.
• Custom docx templates - Review our new Conversion extensions and endpoints to integrate docx templates.
• PDF import & export - Exporting PDF files is not yet supported
• Inline styles - Review our new Conversion extensions and endpoints to integrate inline styles.

Legacy REST API

The legacy document conversion API supports DOCX, ODT, and Markdown conversion from and to Tiptap's JSON format.

/import endpoint

The /import endpoint enables the conversion of docx, odt, or markdown files into Tiptap's JSON format. Users can POST documents to this endpoint and use various parameters to customize how different document elements are handled during the conversion process.

• Method: POST

Required headers

Body

Query parameters

Specify how source document elements are mapped to ProseMirror nodes or marks, and adjust the conversion to meet your specific styling and structural preferences.

/import-docx endpoint (experimental)

The /import-docx endpoint enables the conversion of docx files into Tiptap's JSON format and allows for more docx-specific functions than the /import endpoint. Users can POST documents to this endpoint and use various parameters to customize how different document elements are handled during the conversion process.

• Method: POST

Required headers

Body

Query parameters

Specify how source document elements are mapped to ProseMirror nodes or marks, and adjust the conversion to meet your specific styling and structural preferences.

/export endpoint

The /export endpoint converts Tiptap documents back into formats like docx, odt, or markdown.

• Method: POST

Convert a Tiptap document to a different format.

Required headers

Body

Query parameters