{
"$schema": "https://ui.shadcn.com/schema/registry-item.json",
"name": "docx-io-docs",
"title": "DOCX Import/Export",
"description": "Import DOCX files and export Plate content to Word documents.",
"files": [
{
"path": "../../content/docs/(plugins)/(serializing)/docx-io.mdx",
"content": "---\ntitle: DOCX Import/Export\ndescription: Import DOCX files and export Plate content to Word documents.\n---\n\n\n\n## Features\n\n- **Import DOCX files** to Plate format with full content and comment extraction\n- **Export to DOCX** with support for all common formatting, tables, lists, and images\n- Support for headers, footers, page orientation, and margins\n- Configurable CSS styles and fonts for export\n\n\n\n\n Looking for paste from Word support? See [DOCX Paste](/docs/docx).\n\n\n## Installation\n\n```bash\nnpm install @platejs/docx-io\n```\n\n## Import DOCX\n\n\n\n### Import DOCX File\n\nUse `importDocx` to convert a DOCX file to Plate nodes:\n\n```tsx\nimport { importDocx } from '@platejs/docx-io';\n\nconst handleFileUpload = async (file: File) => {\n const arrayBuffer = await file.arrayBuffer();\n const result = await importDocx(editor, arrayBuffer);\n\n // Insert nodes into editor\n editor.tf.insertNodes(result.nodes);\n\n // Handle comments if needed\n for (const comment of result.comments) {\n console.log(`Comment ${comment.id}: ${comment.text}`);\n }\n\n // Check for conversion warnings\n if (result.warnings.length > 0) {\n console.warn('Conversion warnings:', result.warnings);\n }\n};\n```\n\n\n\n## Export DOCX\n\n\n\n### Basic Export\n\nUse `exportToDocx` to convert Plate content to a DOCX file:\n\n```tsx\nimport { exportToDocx, downloadDocx } from '@platejs/docx-io';\n\nconst handleExport = async () => {\n const blob = await exportToDocx(editor.children, {\n orientation: 'portrait',\n margins: { top: 1440, bottom: 1440, left: 1440, right: 1440 },\n fontFamily: 'Calibri',\n });\n\n downloadDocx(blob, 'document.docx');\n};\n```\n\nOr use the combined function:\n\n```tsx\nimport { exportEditorToDocx } from '@platejs/docx-io';\n\nawait exportEditorToDocx(editor.children, 'document', {\n orientation: 'portrait',\n});\n```\n\n### With Editor Plugins\n\nFor accurate serialization, provide your editor plugins:\n\n```tsx\nimport { exportToDocx } from '@platejs/docx-io';\nimport { BaseEditorKit } from '@/components/editor/editor-base-kit';\nimport { DocxExportKit } from '@/components/editor/plugins/docx-export-kit';\n\nconst blob = await exportToDocx(editor.children, {\n editorPlugins: [...BaseEditorKit, ...DocxExportKit],\n});\n```\n\n### Custom Styles\n\nCustomize the export styles:\n\n```tsx\nimport { exportToDocx, DOCX_EXPORT_STYLES } from '@platejs/docx-io';\n\nconst blob = await exportToDocx(editor.children, {\n customStyles: `\n .custom-highlight { background-color: #ffeb3b; }\n h1 { color: #1a1a1a; }\n `,\n fontFamily: 'Times New Roman',\n});\n```\n\n### Using DocxExportPlugin\n\nFor plugin-based API access:\n\n```tsx\nimport { DocxExportPlugin } from '@platejs/docx-io';\nimport { createPlateEditor } from 'platejs/react';\n\nconst editor = createPlateEditor({\n plugins: [\n // ...otherPlugins,\n DocxExportPlugin.configure({\n options: {\n editorPlugins: myPlugins,\n editorStaticComponent: MyEditorStatic,\n },\n }),\n ],\n});\n\n// Export using plugin API\nconst blob = await editor.api.docxExport.exportToBlob({\n orientation: 'landscape',\n});\n\neditor.api.docxExport.download(blob, 'document');\n\n// Or use transform for export + download\nawait editor.tf.docxExport.exportAndDownload('document', {\n orientation: 'portrait',\n});\n```\n\n\n\n## DOCX Export Kit\n\nThe `DocxExportKit` provides DOCX-optimized static components for elements that require special handling:\n\n\n\nComponents included:\n- **Code blocks**: Inline syntax highlighting with line breaks\n- **Columns**: Table layout instead of flexbox\n- **Equations**: Inline font styling (KaTeX doesn't work in DOCX)\n- **Callouts**: Table layout for icon + content\n- **TOC**: Anchor links with proper paragraph breaks\n\n## Plugins\n\n### DocxExportPlugin\n\nPlugin providing DOCX export functionality with typed API methods.\n\n\n\n\nPlugins to use for HTML serialization. If not provided, uses the editor's current plugins.\n\n\" optional>\nReact component to use for static rendering.\n\n\n\n\n## API\n\n### `importDocx`\n\nImport a DOCX file and convert it to Plate nodes.\n\n\n\n\nThe Plate editor instance.\n\n\nThe DOCX file as ArrayBuffer.\n\n\nImport options.\n\n\n\n\n\nRTF data for image extraction.\n\n\n\n\">\n\nDeserialized editor nodes.\n\n\nComments extracted from the DOCX file.\n\n\nWarnings from mammoth conversion.\n\n\n\n\n### `exportToDocx`\n\nConvert Plate content to a DOCX blob.\n\n\n\n\nThe Plate editor value (array of nodes).\n\n\nExport options.\n\n\n\n\n\nPage orientation.\n\n- **Default:** `'portrait'`\n\n\nPage margins in twentieths of a point (1 inch = 1440).\n\n- **Default:** `{ top: 1440, bottom: 1440, left: 1440, right: 1440, header: 720, footer: 720, gutter: 0 }`\n\n\nFont family for the document body. Overrides default Calibri font.\n\n\nAdditional CSS styles to include. Appended after default DOCX_EXPORT_STYLES.\n\n\nDocument title for metadata.\n\n\nPlugins for HTML serialization.\n\n\nComponent for static rendering.\n\n\n\n\">\nA Blob containing the DOCX file.\n\n\n\n### `downloadDocx`\n\nDownload a DOCX blob as a file.\n\n\n\n\nThe DOCX blob to download.\n\n\nThe filename (with or without .docx extension).\n\n\n\n\n### `exportEditorToDocx`\n\nExport and download editor content as a DOCX file in one call.\n\n\n\n\nThe Plate editor value.\n\n\nThe filename for download.\n\n\nExport options (same as `exportToDocx`).\n\n\n\n\n### api.docxExport.exportToBlob\n\nConvert editor content to a DOCX blob using the plugin API.\n\n\n\n\nPage orientation.\n\n\nPage margins.\n\n\nFont family.\n\n\nAdditional CSS styles.\n\n\nDocument title.\n\n\n\n\">\nA Blob containing the DOCX file.\n\n\n\n### api.docxExport.download\n\nDownload a DOCX blob as a file.\n\n\n\n\nThe DOCX blob.\n\n\nThe filename.\n\n\n\n\n## Transforms\n\n### tf.docxExport.exportAndDownload\n\nExport and download editor content as a DOCX file.\n\n\n\n\nThe filename for download.\n\n\nExport options.\n\n\n\n\n## Types\n\n### DocxComment\n\n```ts\ntype DocxComment = {\n id: string;\n text: string;\n};\n```\n\n### DocxExportMargins\n\n```ts\ntype DocxExportMargins = {\n top?: number;\n bottom?: number;\n left?: number;\n right?: number;\n header?: number;\n footer?: number;\n gutter?: number;\n};\n```\n\n## Constants\n\n### DOCX_EXPORT_STYLES\n\nDefault CSS styles optimized for Microsoft Word HTML rendering:\n\n- Calibri font (Microsoft Office default)\n- 11pt font size with 1.5 line height\n- Heading hierarchy (24pt to 10pt)\n- Table styles with borders\n- Code block styling with Courier New\n- Blockquote styling with left border\n\n## Known Limitations\n\n- **Mobile browsers**: Export may not work reliably on mobile browsers due to limitations with blob handling and downloads.\n- **Complex layouts**: Some complex CSS layouts (flexbox, grid) are converted to table-based layouts for Word compatibility.\n- **Custom fonts**: Only system fonts available in Word will render correctly.\n",
"type": "registry:file",
"target": "content/docs/plate/(plugins)/(serializing)/docx-io.mdx"
}
],
"type": "registry:file"
}