--- title: "Export .docx from your editor" description: "Learn how to export Tiptap editor content to DOCX (Word) files using the Export extension in our docs." canonical_url: "https://tiptap.dev/docs/conversion/export/docx/editor-extension" --- # Export .docx from your editor Learn how to export Tiptap editor content to DOCX (Word) files using the Export 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:** [ExportDocx](https://embed-pro.tiptap.dev/preview/Extensions/ExportDocx) Use Tiptap’s `@tiptap-pro/extension-export-docx` to export the editor’s content as a `.docx` file. This extension works in any JavaScript environment, including server-side applications, due to the isomorphic nature of the `exportDocx` function. You can also export via the [REST API](https://tiptap.dev/docs/conversion/export/docx/rest-api.md). Both paths use the same conversion library. The main differences: | | Editor extension | REST API | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | | Runs in | Your app (client or server-side) | Tiptap cloud | | Custom node rendering | Supported via [`customNodes`](https://tiptap.dev/docs/conversion/export/docx/custom-nodes.md) | Not yet supported\* | | Element overrides | [`paragraphOverrides`, `textRunOverrides`, `tableOverrides`, `tableCellOverrides`, `imageOverrides`](https://tiptap.dev/docs/conversion/export/docx/styles.md#element-overrides), plus [`headerFooterOverrides`](https://tiptap.dev/docs/conversion/export/docx/styles.md#headerfooteroverrides) for header/footer-scoped overrides | Not yet supported\* | | Style overrides | Supported | Supported | | Headers and footers | docx.js objects or auto-extracted from Pages | Plain text or stringified JSON | \* The REST API does not currently accept `customNodes` or any of the element-override fields. Requests carrying them have those fields stripped during validation and the export proceeds with defaults. Bringing both surfaces to parity is on the roadmap; until then, use the editor extension if you need custom node rendering or element overrides. Choose the REST API for simple exports that only need style customization. Use the editor extension when you need custom node rendering, element overrides, or full control over the output. By default, the extension maps Tiptap nodes to DOCX elements. If your content includes custom nodes, configure their [export behavior](https://tiptap.dev/docs/conversion/export/docx/custom-nodes.md) to ensure they’re properly converted. ## Install the DOCX 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 DOCX** extension package ```bash npm i @tiptap-pro/extension-export-docx ``` Using the export extension does not require any Tiptap Conversion credentials, since the conversion is handled right away in the extension. ```js import { ExportDocx } from '@tiptap-pro/extension-export-docx' ``` ## Configuring the extension The `ExportDocx` extension can be configured with an `ExportDocxOptions` (`object`) as an argument to the `configure` method with the following properties: ```ts // Import the ExportDocx extension import { ExportDocx } from '@tiptap-pro/extension-export-docx' const editor = new Editor({ extensions: [ // Other extensions ... ExportDocx.configure({ onCompleteExport: (result: string | Buffer | Blob | Stream) => void, // required exportType: 'blob', // optional. Default: 'blob' customNodes: [], // optional. Default: [] styleOverrides: {}, // optional. Default: {} paragraphOverrides: {}, // optional. Default: {} textRunOverrides: {}, // optional. Default: {} tableOverrides: {}, // optional. Default: {} tableCellOverrides: {}, // optional. Default: {} imageOverrides: {}, // optional. Default: {} numberingFormats: undefined, // optional. Default: undefined headerFooterOverrides: undefined, // optional. Default: undefined fonts: undefined, // optional. Default: undefined embedFonts: false, // optional. Default: false appId: undefined, // optional. Default: undefined token: undefined, // optional. Default: undefined endpoint: undefined, // optional. Default: undefined }), // Other extensions ... ], // Other editor settings ... }) ``` | Parameter | Description | Default | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | | onCompleteExport | A **required** callback function that receives the exported data. You can then handle the data as needed (e.g., prompt a file download) | `N/A` | | options | An object to configure some parts of the export:**exportType**: The type of data returned by the method:- **buffer**: Returns a Node.js `Buffer` (server-side only)- **stream**: Returns a Node.js `Stream` (server-side only)- **string**: Returns a `String`- **blob**: Returns a `Blob` | `blob` | | customNodes | An array of custom node definitions. If your content includes custom nodes, pass their definitions here to ensure they're properly converted | `[]` | | styleOverrides | An object with custom styles to apply to the exported document. [See Export styles](https://tiptap.dev/docs/conversion/export/docx/styles.md) | `{}` | | paragraphOverrides | Base defaults for all paragraphs (also applied to header/footer content). [See Element overrides](https://tiptap.dev/docs/conversion/export/docx/styles.md#element-overrides) | `{}` | | textRunOverrides | Base defaults for all text runs (also applied to header/footer content). [See Element overrides](https://tiptap.dev/docs/conversion/export/docx/styles.md#element-overrides) | `{}` | | tableOverrides | Table-level property overrides (also applied to header/footer tables). [See Element overrides](https://tiptap.dev/docs/conversion/export/docx/styles.md#element-overrides) | `{}` | | tableCellOverrides | Base defaults for all table cells (also applied to header/footer cells). [See Element overrides](https://tiptap.dev/docs/conversion/export/docx/styles.md#element-overrides) | `{}` | | imageOverrides | Image property overrides (also applied to images in headers/footers). [See Element overrides](https://tiptap.dev/docs/conversion/export/docx/styles.md#element-overrides) | `{}` | | numberingFormats | Registry of multilevel ordered-list numbering format definitions. Each entry's `id` matches the `numberingFormat` attribute on the outermost `
    `; unknown / missing ids fall back to plain `1. 2. 3.` numbering. Pair this with `OrderedListNumbering` and `generateNumberingFormatCss` from `@tiptap-pro/extension-convert-kit`. [See Ordered list numbering](https://tiptap.dev/docs/conversion/export/docx/ordered-list-numbering.md) | `undefined` | | headerFooterOverrides | Per-field overrides scoped to header/footer content only — fully replace the matching body-wide override inside headers and footers. Only applies to headers/footers auto-extracted from the [Pages extension](https://tiptap.dev/docs/pages/getting-started/overview.md). [See `headerFooterOverrides`](https://tiptap.dev/docs/conversion/export/docx/styles.md#headerfooteroverrides) | `undefined` | | fonts | Custom TTF/OTF fonts to embed so the file renders with the intended fonts even on machines where they aren't installed. [See Fonts](https://tiptap.dev/docs/conversion/export/docx/fonts.md) | `undefined` | | embedFonts | Automatically detect the fonts the document uses, locate them via the page's `@font-face` rules (with a Google Fonts fallback), convert WOFF2 to TTF through the Convert Service, and embed them. Browser only. [See Fonts](https://tiptap.dev/docs/conversion/export/docx/fonts.md) | `false` | | appId | Tiptap Convert app ID, sent only when `embedFonts` needs to convert a WOFF2 font. [See Fonts](https://tiptap.dev/docs/conversion/export/docx/fonts.md) | `undefined` | | token | Tiptap Convert JWT, sent only when `embedFonts` needs to convert a WOFF2 font. [See Fonts](https://tiptap.dev/docs/conversion/export/docx/fonts.md) | `undefined` | | endpoint | Tiptap Convert REST endpoint base used for WOFF2 → TTF conversion. [See Fonts](https://tiptap.dev/docs/conversion/export/docx/fonts.md) | `https://api.tiptap.dev/v2/convert` | > **Page-number token names are configured on Pages, not here:** > > There is no `placeholders` option on `ExportDocx`. To rename the built-in `{page}` / `{total}` > tokens or disable substitution, configure it on the [Pages > extension](https://tiptap.dev/docs/pages/core-concepts/page-header-footer.md#renaming-or-disabling-placeholders) — the > export honors the same token names, so the editor preview and the exported `.docx` stay > consistent. ## Export a DOCX file With the extension installed, you can convert your editor’s content to `.docx`. Before diving into an example, let's take a look into the signature of the `exportDocx` method available in your editor's commands: ```ts /** * Export the current document as a .docx file * * Notes: 'buffer' and 'stream' export types are only available in the server environment * as they use the Node Buffer and Stream APIs respectively * * @param onCompleteExport - Callback function to handle the exported file * @param options - Export options * @param customNodes - Custom node definitions to ensure proper conversion * @param styleOverrides - Custom styles to apply to the exported document * @example editor.commands.exportDocx((result) => {}, { exportType: 'buffer' }, []) * */ exportDocx: (options?: ExportDocxOptions) => Promise | Blob | Stream> ``` The `exportDocx` method takes an optional `ExportDocxOptions` (`object`) as an argument with the following properties that you can use to *override* the ones that you have configured with the `ExportDocx.configure` method: | Parameter | Description | Default | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | | onCompleteExport | A **required** callback function (if you haven't defined it in the configure extension call) that receives the exported data. You can then handle the data as needed (e.g., prompt a file download) | `N/A` | | options | An object to configure some parts of the export:**exportType**: The type of data returned by the method:- **buffer**: Returns a Node.js `Buffer` (server-side only)- **stream**: Returns a Node.js `Stream` (server-side only)- **string**: Returns a `String`- **blob**: Returns a `Blob` | `blob` | | customNodes | An array of custom node definitions. If your content includes custom nodes, pass their definitions here to ensure they're properly converted | `[]` | | styleOverrides | An object with custom styles to apply to the exported document. [See Export styles](https://tiptap.dev/docs/conversion/export/docx/styles.md) | `{}` | | paragraphOverrides | Base defaults for all paragraphs (also applied to header/footer content). [See Element overrides](https://tiptap.dev/docs/conversion/export/docx/styles.md#element-overrides) | `{}` | | textRunOverrides | Base defaults for all text runs (also applied to header/footer content). [See Element overrides](https://tiptap.dev/docs/conversion/export/docx/styles.md#element-overrides) | `{}` | | tableOverrides | Table-level property overrides (also applied to header/footer tables). [See Element overrides](https://tiptap.dev/docs/conversion/export/docx/styles.md#element-overrides) | `{}` | | tableCellOverrides | Base defaults for all table cells (also applied to header/footer cells). [See Element overrides](https://tiptap.dev/docs/conversion/export/docx/styles.md#element-overrides) | `{}` | | imageOverrides | Image property overrides (also applied to images in headers/footers). [See Element overrides](https://tiptap.dev/docs/conversion/export/docx/styles.md#element-overrides) | `{}` | | numberingFormats | Registry of multilevel ordered-list numbering format definitions. Each entry's `id` matches the `numberingFormat` attribute on the outermost `
      `; unknown / missing ids fall back to plain `1. 2. 3.` numbering. Pair this with `OrderedListNumbering` and `generateNumberingFormatCss` from `@tiptap-pro/extension-convert-kit`. [See Ordered list numbering](https://tiptap.dev/docs/conversion/export/docx/ordered-list-numbering.md) | `undefined` | | headerFooterOverrides | Per-field overrides scoped to header/footer content only — fully replace the matching body-wide override inside headers and footers. Only applies to headers/footers auto-extracted from the [Pages extension](https://tiptap.dev/docs/pages/getting-started/overview.md). [See `headerFooterOverrides`](https://tiptap.dev/docs/conversion/export/docx/styles.md#headerfooteroverrides) | `undefined` | | fonts | Custom TTF/OTF fonts to embed so the file renders with the intended fonts even on machines where they aren't installed. [See Fonts](https://tiptap.dev/docs/conversion/export/docx/fonts.md) | `undefined` | | embedFonts | Automatically detect the fonts the document uses, locate them via the page's `@font-face` rules (with a Google Fonts fallback), convert WOFF2 to TTF through the Convert Service, and embed them. Browser only. [See Fonts](https://tiptap.dev/docs/conversion/export/docx/fonts.md) | `false` | | appId | Tiptap Convert app ID, sent only when `embedFonts` needs to convert a WOFF2 font. [See Fonts](https://tiptap.dev/docs/conversion/export/docx/fonts.md) | `undefined` | | token | Tiptap Convert JWT, sent only when `embedFonts` needs to convert a WOFF2 font. [See Fonts](https://tiptap.dev/docs/conversion/export/docx/fonts.md) | `undefined` | | endpoint | Tiptap Convert REST endpoint base used for WOFF2 → TTF conversion. [See Fonts](https://tiptap.dev/docs/conversion/export/docx/fonts.md) | `https://api.tiptap.dev/v2/convert` | ```js // Import the ExportDocx extension import { ExportDocx } from '@tiptap-pro/extension-export-docx' // Setup you editor const editor = new Editor({ extensions: [ // Other extensions ... ExportDocx.configure({ onCompleteExport: (result: string | Buffer | Blob | Stream) => {}, // required exportType: 'blob', // optional. Default: 'blob' customNodes: [], // optional. Default: [] styleOverrides: {}, // optional. Default: {} paragraphOverrides: {}, // optional. Default: {} textRunOverrides: {}, // optional. Default: {} tableOverrides: {}, // optional. Default: {} tableCellOverrides: {}, // optional. Default: {} imageOverrides: {}, // optional. Default: {} headerFooterOverrides: undefined, // optional. Default: undefined fonts: undefined, // optional. Default: undefined embedFonts: false, // optional. Default: false appId: undefined, // optional. Default: undefined token: undefined, // optional. Default: undefined endpoint: undefined, // optional. Default: undefined }), // Other extensions ... ], // Other editor settings ... }) // Declare some functions that will call the exportDocx method from your editor function handleExportDocx() { // Call your editor's exportDocx method editor .chain() // Method call without any overrides // It will take the configuration set in the configure method .exportDocx() .run() } function handleExportDocxBuffer() { // Call your editor's exportDocx method editor .chain() // Method call with some overrides .exportDocx({ // Override the onCompleteExport callback to handle the override exported type onCompleteExport: (result: Buffer) => { // Handle the exported file in a buffer format }, // Override the export type exportType: 'Buffer', }) .run() } // Call those functions at any point in your application handleExportDocx() handleExportDocxBuffer() ``` ### How it works The above example runs entirely in the browser, generating a DOCX Blob via the ExportDocx extension since it's the default value for the `exportType` as we haven't override it. We then programmatically download the file. You can adjust this logic, for instance, to send the blob to a server instead of downloading. | Parameter | Description | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | onCompleteExport | When the conversion completes, we will get the `result` of the conversion as the main and only argument to the callback function which, in this case, it would be a `Blob` since we've declared that we wanted this type in the `exportType` within the `options` parameter. You can then handle it however you prefer, e.g. prompting a file download, like we showcased in the example above. | | exportType | We're using the default `blob` so the conversion returns a `Blob`. | | customNodes | We won't provide any custom node mapping since we are not providing any custom nodes. | | styleOverrides | We won't provide any style overrides, and therefore, a default `DOCX` style is set following some common guideliness from Microsoft Word defaults and they will be applied to the exported document. | ## Server-side export For applications requiring complex document generation or to reduce client-side bundle size, you can export `.docx` files in your the server. In order to do so, you'd need to import the `exportDocx` function from the `@tiptap-pro/extension-export-docx` package, pass it your Tiptap JSON content, and return the resulting conversion to the client. Let's first take a look into the `exportDocx` function signature: ```ts /** * Export the current document as a .docx file * * Notes: 'buffer' and 'stream' export types are only available in the server environment * as they use the Node Buffer and Stream APIs respectively * * @param options.document - The JSON representation of the document * @param options.exportType - The type of export to perform * @param options.customNodes - Custom node definitions * @param options.styleOverrides - Style overrides for the exported document * @param options.paragraphOverrides - Base defaults for all paragraphs * @param options.textRunOverrides - Base defaults for all text runs * @param options.tableOverrides - Table-level property overrides * @param options.tableCellOverrides - Base defaults for all table cells * @param options.imageOverrides - Image property overrides * @example exportDocx({ document: editor.getJSON(), exportType: 'blob', customNodes: [], styleOverrides: {} }) */ async function exportDocx({ document, exportType, customNodes, styleOverrides, paragraphOverrides, textRunOverrides, tableOverrides, tableCellOverrides, imageOverrides, }: ExportDocxOptions) {} ``` The `exportDocx` function will return a `docx` document ready and converted to any format that . Here you have a simple example using `Express` and `@tiptap-pro/extension-export-docx` on the server-side: ```ts import { exportDocx } from '@tiptap-pro/extension-export-docx' import express from 'express' const app = express() app.post('/export-docx', async (req, res) => { try { // Get Tiptap JSON content from the request or from your database const { content } = req.body // Convert Tiptap JSON to DOCX const docxBuffer = await exportDocx({ document: content }) // Send as a downloadable file res.setHeader( 'Content-Type', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', ) res.setHeader('Content-Disposition', 'attachment; filename="document.docx"') res.send(docxBuffer) } catch (error) { res.status(500).json({ error: error.message }) } }) ``` ## Node attribute inference The DOCX export automatically respects node-level attributes set by the editor, rather than always computing values from scratch. This means resized images, adjusted table columns, and other editor-level customizations are preserved in the exported document. | Feature | Description | | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Image `width`/`height`** | When an image has been resized in the editor, the user-set dimensions are used. Priority: `imageOverrides.transformation` > `node.attrs.width/height` > intrinsic dimensions | | **Image `alt` text** | Mapped to the docx `altText` property for accessibility metadata | | **Table cell `colwidth`** | Per-cell pixel array from editor-resized columns produces precise column widths in the export | | **Table cell `rowspan`** | Cells spanning multiple rows are correctly exported | | **Paragraph `textAlign: 'justify'`** | Correctly mapped to `AlignmentType.JUSTIFIED` (previously fell through to left alignment) | | **Text run `backgroundColor`** | `textStyle` mark `backgroundColor` exported as solid character shading | | **Paragraph/heading `lineHeight`** | Proportional line height — a unitless multiple (e.g. `1.5`) or a percentage (e.g. `150%`) — is written as DOCX line spacing. Fixed `px`/`pt` line heights have no proportional equivalent and are skipped | | **Paragraph/heading spacing** | `spacingBefore` and `spacingAfter` are written as space before/after the paragraph | | **Paragraph/heading indentation** | `indent` and `firstLineIndent` are written as left and first-line indentation; a negative `firstLineIndent` becomes a hanging indent | | **Paragraph/heading `contextualSpacing`** | Suppresses spacing between adjacent paragraphs of the same style in the export | ## What to expect - **No authentication required.** The export runs entirely in the browser (or your Node.js server using the same package). No JWT, no App ID, no API call. - **Browser and server-side environments are both supported** via the same package. The server-side example above shows the Node.js path; the browser path is the default. - **Synchronous result delivery.** The `onCompleteExport` callback receives the exported file directly — as a `Blob`, `Buffer`, `Stream`, or `string` depending on `exportType`. ## What not to expect - **Round-trip identity.** Importing a DOCX, editing it, and exporting it back is not byte-identical. A handful of attributes (tab stops, and fixed `px`/`pt` line heights) are extracted on import but not written on export today. See the [feature support matrix](https://tiptap.dev/docs/conversion/getting-started/feature-support-matrix.md) for the full list. - **Pixel-perfect Word match.** We aim for visually faithful round-trips on the supported feature set; absolute parity with Word's rendering engine is out of scope. - **Page layout from the editor.** DOCX export preserves headers, footers, and page-format settings you configure on the export options. It does not infer page boundaries from on-screen pagination — pair with the [Pages extension](https://tiptap.dev/docs/pages/getting-started/overview.md) when you need pagination-aware exports. ## Support & Limitations For a detailed breakdown of which document features are supported at each stage of the pipeline, see the [Supported features](https://tiptap.dev/docs/conversion/getting-started/feature-support-matrix.md) matrix.