Convert ODT with Tiptap

OpenDocument Text .odt is a widely used format in LibreOffice and OpenOffice. Tiptap’s Conversion tools provide three ways to work with ODT files:

Editor Import – Convert .odt files directly into Tiptap JSON for in-editor editing.
Editor Export – Convert the current Tiptap editor content into an .odt file.
REST API – Integrate ODT conversions on the server side or from external services with the ODT Conversion REST API.

Integrate or test Conversion

To test or integrate this feature you need an active trial or Tiptap subscription.

Editor ODT Import

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

To import .odt documents into your editor install the Import extension

npm i @tiptap-pro/extension-import

Add and configure the extension in your editor setup

Configure the 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 token 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',
    }),
  ],
})

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()

Options

Name	Type	Default	Description
`appId`	`string`	`undefined`	The convert app ID from the Convert settings page: https://cloud.tiptap.dev/convert-settings
`token`	`string`	`undefined`	The JWT token generated from your server via secret
`imageUploadCallbackUrl`	`string`	`undefined`	The URL to upload images to, if not provided, images will be stripped from the document, see more info

Commands

Name	Description
`import`	Import a file into the editor

`import`

Arguments

Name	Type	Default	Options	Description
`file`	`File`	`undefined`	Any file	The file to import
`format`	`string`	`undefined`	`gfm`	Not relevant for the ODT file type
`onImport`	`Function`	`undefined`	`fn(context)`	A callback used to customize the import behavior. The context argument includes information about the content, errors and a `setEditorContent` function to modify the content

Editor ODT Export

To use the convert extension, you need to install the @tiptap-pro/extension-export package:

npm i @tiptap-pro/extension-export

Configure the 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 token 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
  },
})

Options

Name	Type	Default	Description
`appId`	`string`	`undefined`	The convert app ID from the Convert settings page: https://cloud.tiptap.dev/convert-settings
`token`	`string`	`undefined`	The JWT token generated from your server via secret

Commands

Name	Description
`export`	Export the editor content

`export`

Arguments

Name	Type	Default	Options	Description
`format`	`string`	`undefined`	`docx,odt,md,gfm`	The format you want to export to
`content`	`JSONContent`	`undefined`	Any Tiptap JSON	The Tiptap JSON content you want to export
`onExport`	`Function`	`undefined`	`fn(context)`	A callback used to customize the export behavior. The context argument includes information about the blob, filename, errors and a `download` function to download the document directly