---
title: "Convert ODT with Tiptap (Legacy)"
description: "Learn how to handle ODT files (OpenDocument Text) in a Tiptap editor using the legacy import/export extensions."
canonical_url: "https://tiptap.dev/docs/conversion/legacy/odt/editor-extensions"
---

# Convert ODT with Tiptap (Legacy)

Learn how to handle ODT files (OpenDocument Text) in a Tiptap editor using the legacy import/export extensions.

> **Legacy ODT Editor Extensions (Deprecated):**
>
> These editor extensions are deprecated and will be sunset at some point in 2026 with prior communication from the team. For new integrations, use the updated [ODT export extensions](https://tiptap.dev/docs/conversion/export/odt/editor-extension.md) and [import extensions](https://tiptap.dev/docs/conversion/import/docx/editor-extension.md).

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](https://tiptap.dev/docs/conversion/legacy/odt/rest-api.md).

* **1. Activate trial or subscribe**

  Start a [free trial](https://cloud.tiptap.dev/v2?trial=true) or [subscribe to the Start plan](https://cloud.tiptap.dev/v2/billing) in your account.
* **2. Install from private registry**

  To install this frontend extensions, authenticate to Tiptap's private npm registry by following the [setup guide](https://tiptap.dev/docs/guides/pro-extensions.md).

## Editor ODT Import

The Conversion extensions are published in Tiptap's private npm registry. Integrate the extensions by following the [private registry guide](https://tiptap.dev/docs/guides/pro-extensions.md).

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

```bash
npm i @tiptap-pro/extension-import
```

Add and configure the extension in your editor setup

### Configure the extension

```js
// 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',
    }),
  ],
})
```

### Import your first document

```js
// 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

```js
// 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](https://cloud.tiptap.dev/convert-settings) |
| `token`                  | `string` | `undefined` | The JWT 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                                                   |

### 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:

```bash
npm i @tiptap-pro/extension-export
```

### Configure the extension

```js
// 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

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

### Customize the export behavior

```js
// 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](https://cloud.tiptap.dev/convert-settings) |
| `token` | `string` | `undefined` | The JWT 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 |