--- title: "Export EPUB from your editor" description: "Learn how to export Tiptap editor content to EPUB files using the Export EPUB extension in our docs." canonical_url: "https://tiptap.dev/docs/conversion/export/epub/editor-extension" --- # Export EPUB from your editor Learn how to export Tiptap editor content to EPUB files using the Export EPUB extension in our docs. - **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). > **Interactive demo:** [ExportEpub](https://embed-pro.tiptap.dev/preview/Extensions/ExportEpub) Use Tiptap's `@tiptap-pro/extension-export-epub` to export your editor's content as an `.epub` file. This extension integrates EPUB export functionality into your editor by sending the document to the Tiptap convert service for conversion. You can also use the [REST API](https://tiptap.dev/docs/conversion/export/epub/rest-api.md) instead if you'd prefer to handle the conversion on your end. ## Install the EPUB Export extension 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). Once done you can install and import the **Export EPUB** extension package. ```bash npm i @tiptap-pro/extension-export-epub ``` ```js import { ExportEpub } from '@tiptap-pro/extension-export-epub' ``` ## Configuring the extension The `ExportEpub` extension can be configured with an `ExportEpubOptions` (`object`) as an argument to the `configure` method with the following properties: ```ts import { ExportEpub } from '@tiptap-pro/extension-export-epub' const editor = new Editor({ extensions: [ // Other extensions ... ExportEpub.configure({ endpoint: 'https://api.tiptap.dev/v2/convert', token: 'YOUR_TOKEN', appId: 'YOUR_APP_ID', styleOverrides: {}, headers: {}, footers: {}, pageSize: { width: '21cm', height: '29.7cm' }, pageMargins: { top: '1cm', bottom: '1cm', left: '1cm', right: '1cm' }, customNodes: [], onCompleteExport: (result) => { // Handle the exported Blob }, }), // Other extensions ... ], }) ``` | Parameter | Type | Description | Default | | ------------------ | ------------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------- | | `endpoint` | `string` | The Tiptap API endpoint for conversion | `'https://api.tiptap.dev/v2/convert'` | | `token` | `string` | The Tiptap JWT for authentication | `''` | | `appId` | `string` | The Tiptap App ID for authentication | `''` | | `styleOverrides` | `Record` | Style overrides to apply to the export | `undefined` | | `headers` | `HeaderConfig` | Header configuration for the exported document | `undefined` | | `footers` | `FooterConfig` | Footer configuration for the exported document | `undefined` | | `pageSize` | `PageSize` | Page size configuration | `undefined` | | `pageMargins` | `PageMargins` | Page margins configuration | `undefined` | | `customNodes` | `CustomNodeDefinition[]` | Custom node definitions for DOCX-based conversion (requires `@tiptap-pro/extension-export-docx`) | `undefined` | | `onCompleteExport` | `(result: Blob) => void` | Callback that receives the exported file as a Blob | Throws error if not provided | ### HeaderConfig | Property | Type | Description | | -------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `evenAndOddHeaders` | `boolean` | Whether to use different headers for odd and even pages | | `differentFirstPage` | `boolean` | Whether to use a different header on the first page. When `true`, the `first` value is used on page one instead of `default`. | | `default` | `string` | The standard default header on every page, or header on odd pages when `evenAndOddHeaders` is active. Accepts a plain text string or stringified Tiptap JSONContent for rich formatting. | | `first` | `string` | The header on the first page. Only used when `differentFirstPage` is set to `true`. Accepts a plain text string or stringified Tiptap JSONContent for rich formatting. | | `even` | `string` | The header on even pages when the `evenAndOddHeaders` option is activated. Accepts a plain text string or stringified Tiptap JSONContent for rich formatting. | ### FooterConfig | Property | Type | Description | | -------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `evenAndOddFooters` | `boolean` | Whether to use different footers for odd and even pages | | `differentFirstPage` | `boolean` | Whether to use a different footer on the first page. When `true`, the `first` value is used on page one instead of `default`. | | `default` | `string` | The standard default footer on every page, or footer on odd pages when `evenAndOddFooters` is active. Accepts a plain text string or stringified Tiptap JSONContent for rich formatting. | | `first` | `string` | The footer on the first page. Only used when `differentFirstPage` is set to `true`. Accepts a plain text string or stringified Tiptap JSONContent for rich formatting. | | `even` | `string` | The footer on even pages when the `evenAndOddFooters` option is activated. Accepts a plain text string or stringified Tiptap JSONContent for rich formatting. | ### PageSize | Property | Type | Description | Default | | -------- | -------- | ---------------------------------------------------------------------------------------------------- | ---------- | | `width` | `string` | The width of the page. Must be a positive number followed by a valid unit (cm, in, pt, pc, mm, px). | `"21cm"` | | `height` | `string` | The height of the page. Must be a positive number followed by a valid unit (cm, in, pt, pc, mm, px). | `"29.7cm"` | ### PageMargins | Property | Type | Description | Default | | -------- | -------- | ------------------------------------------------------------------------------------------------------------------- | ------- | | `top` | `string` | The top margin of the page. Can be negative. Must be a number followed by a valid unit (cm, in, pt, pc, mm, px). | `"1cm"` | | `bottom` | `string` | The bottom margin of the page. Can be negative. Must be a number followed by a valid unit (cm, in, pt, pc, mm, px). | `"1cm"` | | `left` | `string` | The left margin of the page. Must be a positive number followed by a valid unit (cm, in, pt, pc, mm, px). | `"1cm"` | | `right` | `string` | The right margin of the page. Must be a positive number followed by a valid unit (cm, in, pt, pc, mm, px). | `"1cm"` | ## Export an EPUB file With the extension installed, you can export your editor's content to `.epub` using the `exportEpub` command. ```ts /** * Export the current document as an EPUB file via the Tiptap convert service. * * @param options - All extension-level options can be overridden per-invocation * @example editor.commands.exportEpub({ onCompleteExport: (result) => {} }) */ exportEpub: (options?: ExportEpubCommandOptions) => ReturnType ``` The `ExportEpubCommandOptions` interface extends `ExportEpubOptions`, so every configuration option can be overridden per-command invocation: | Property | Type | Description | | ------------------ | ------------------------ | --------------------------------------------------------- | | `endpoint` | `string` | Override the API endpoint for this specific export | | `token` | `string` | Override the JWT token for this specific export | | `appId` | `string` | Override the App ID for this specific export | | `styleOverrides` | `Record` | Override style overrides for this specific export | | `headers` | `HeaderConfig` | Override header configuration for this specific export | | `footers` | `FooterConfig` | Override footer configuration for this specific export | | `pageSize` | `PageSize` | Override page size for this specific export | | `pageMargins` | `PageMargins` | Override page margins for this specific export | | `customNodes` | `CustomNodeDefinition[]` | Override custom node definitions for this specific export | | `onCompleteExport` | `(result: Blob) => void` | Override the callback for this specific export | ```js import { ExportEpub } from '@tiptap-pro/extension-export-epub' const editor = new Editor({ extensions: [ // Other extensions ... ExportEpub.configure({ token: 'YOUR_TOKEN', appId: 'YOUR_APP_ID', onCompleteExport(result) { // Download the EPUB file const url = URL.createObjectURL(result) const a = document.createElement('a') a.href = url a.download = 'document.epub' a.click() URL.revokeObjectURL(url) }, }), // Other extensions ... ], }) // Use the extension-level callback editor.chain().exportEpub().run() // Or override options for a specific export editor .chain() .exportEpub({ pageSize: { width: '8.5in', height: '11in' }, onCompleteExport(result) { // Custom handling for this specific export const url = URL.createObjectURL(result) window.open(url) }, }) .run() ``` ### How it works When you call `exportEpub`, the extension sends the editor's document and any configured options (style overrides, page layout, headers, footers) to the Convert service, which returns the resulting `.epub` file as a binary blob. The `onCompleteExport` callback receives the blob directly. Errors are thrown as exceptions rather than passed through the callback. ## What to expect - **Authentication required** (`token` JWT and `appId`). Generate JWTs server-side. See the [Conversion install guide](https://tiptap.dev/docs/conversion/getting-started/install.md). - **HTTP responses to handle:** `401` (missing or invalid JWT), `403` (operation not permitted for your app — typically a format your plan doesn't include), `5xx` (transient server-side error; retry with backoff). - **Each request is processed end-to-end before responding.** Plan for longer round-trips on long documents. ## What not to expect - **Per-chapter metadata customisation.** EPUB metadata (book title, author, language, custom chapter spine) is not yet configurable through the export options. - **Pixel-perfect rendering across reading apps.** EPUB rendering is reading-app-dependent; spacing, font fallback, and image scaling vary across apps and devices. Test against the readers your audience uses. ## Support & Limitations | **Feature** | **Support** | | -------------------------------- | --------------------------------------------------------------------------- | | **Text content** | ✓ Basic text, spacing, punctuation | | **Text formatting** | ✓ Bold, italic, underline, strikethrough, alignment, line height | | **Block elements** | ✓ Paragraphs, headings (1–6), blockquotes, ordered and unordered lists | | **Tables** | ✓ Basic structure, header rows, colspan | | **Links** | ✓ Hyperlinks | | **Media (Images)** | ✓ Embedded images, size preserved | | **Styles** | ✓ Font families\*, Font colors, font sizes, background colors, line heights | | **Headers & Footers** | ✓ | | **Math** | ✓ | | **Page Breaks** | ✓ | | **Sections** | ✗ | | **Footnotes & Endnotes** | ✗ | | **Comments & Revisions** | ✗ | | **Table of Contents** | ✗ | | **Advanced Formatting** | ✗ Columns, text direction, forms, macros, embedded scripts | | **Metadata** | ✗ | | **Text Boxes, Shapes, SmartArt** | ✗ | - Font families are supported as long as the target font is installed on the operative system when the exported file is opened. For a detailed per-feature breakdown, see the [Supported features](https://tiptap.dev/docs/conversion/getting-started/feature-support-matrix.md) matrix. Note that element overrides (`paragraphOverrides`, `textRunOverrides`, `tableOverrides`, `tableCellOverrides`, `imageOverrides`) available in the [DOCX export extension](https://tiptap.dev/docs/conversion/export/docx/editor-extension.md) are not passed through to the EPUB conversion.