Export .docx from your editor
Use Tiptap’s @tiptap-pro/extension-export-docx
to export the editor's content as a .docx
file. This extension integrates DOCX
export functionality into your editor.
You can use this extension under any JavaScript environment, including server-side applications due to the isomorphic nature of the exportDocx
function.
You can also use the REST API instead if you'd prefer to handle the conversion on our end.
By default, the extension maps Tiptap nodes to DOCX elements. If your content includes custom nodes, configure their export behavior to ensure they’re properly converted.
Subscription required
This extension requires a valid Tiptap subscription. As a paid subscriber you can install the extension by accessing our private registry.
Install the DOCX Export extension
Install and import the Export DOCX extension package
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.
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:
// 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<ArrayBufferLike> | Blob | Stream) => void, // required
exportType: 'blob', // optional. Default: 'blob'
customNodes: [], // optional. Default: []
styleOverrides: {}, // optional. Default: {}
}),
// 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. Use this to override the default export styles | {} |
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:
/**
* 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<string | Buffer<ArrayBufferLike> | 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. Use this to override the default export styles | {} |
// 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<ArrayBufferLike> | Blob | Stream) => {}, // required
exportType: 'blob', // optional. Default: 'blob'
customNodes: [], // optional. Default: []
styleOverrides: {}, // optional. Default: {}
}),
// 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:
/**
* 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
* @example exportDocx({ document: editor.getJSON(), exportType: 'blob', customNodes: [], styleOverrides: {} })
*/
async function exportDocx ({ document, exportType, customNodes, styleOverrides }: 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:
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 })
}
})
Support & Limitations
Exporting .docx
files from Tiptap JSON provides a way to handle most standard Word content, but it’s not a one-to-one mapping due to inherent differences between DOCX formatting and Tiptap’s CSS-based styles.
Currently supported features and known 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 | ~ In development |
Sections & Page Breaks | ~ In development |
Footnotes & Endnotes | ~ In development |
Math | ~ In development |
Comments & Revisions | ✗ |
Table of Contents | ✗ |
Advanced Formatting | ✗ Columns, text direction, forms, macros, embedded scripts |
Metadata | ✗ |
Text Boxes, Shapes, SmartArt | ✗ |
.docx
file is opened.