--- title: "DOCX Editor" description: "A paginated, Word-style document editor built on Tiptap Pages with real-time collaboration, editable headers and footers, footnotes, page breaks, a live Word preview, and DOCX/PDF export." canonical_url: "https://tiptap.dev/docs/ui-components/templates/docx-editor" --- # DOCX Editor A paginated, Word-style document editor built on Tiptap Pages with real-time collaboration, editable headers and footers, footnotes, page breaks, a live Word preview, and DOCX/PDF export. The **DOCX Editor Template** is a paginated, Word-style document editor. Unlike the continuous-canvas editors, it renders content on discrete pages with real margins, editable headers and footers, footnotes, manual page breaks, and a configurable page format—then exports a faithful `.docx` file and renders a live Word preview next to the editor. It is built on the [Tiptap Pages](https://tiptap.dev/docs/pages/getting-started/overview.md) extension and the [Conversion](https://tiptap.dev/docs/conversion/getting-started/overview.md) DOCX/PDF exporters, with real-time collaboration provided by [Tiptap Collaboration](https://tiptap.dev/docs/collaboration/getting-started/overview.md). [View in Full Screen](https://template.tiptap.dev/docx) > **Interactive demo:** [docx](https://template.tiptap.dev/docx) > **Team plan required:** > > The DOCX Editor template requires at least a **Team plan** subscription to use in production. You > can integrate and test it during your trial period. Usage of this template is subject to our > [Terms of Service](https://tiptap.dev/terms-of-service) and [Pro > License](https://tiptap.dev/pro-license). ## Overview The template combines several Tiptap Pro extensions into a single document-editing experience: - **[Pages](https://tiptap.dev/docs/pages/getting-started/overview.md)** — pagination, page format (size, orientation, margins), headers and footers, footnotes, and zoom. - **[Convert / Export DOCX](https://tiptap.dev/docs/conversion/export/docx/editor-extension.md)** — turns the editor document into a real Word `.docx` file in the browser. - **[Export PDF](https://tiptap.dev/docs/conversion/export/pdf/editor-extension.md)** — generates the side-by-side Word preview through the Tiptap Conversion API. - **[Collaboration](https://tiptap.dev/docs/collaboration/getting-started/overview.md)** — real-time multi-user editing of the body, headers, footers, and footnotes. On top of these, the template adds a Word-like toolbar, a document-settings sidebar, an editable header/footer overlay, and a set of small workarounds that make the Pages interactions feel native. ## Installation You'll need a Tiptap account with an active subscription or trial. Create one at [cloud.tiptap.dev/register](https://cloud.tiptap.dev/register). ### For existing projects ```bash npx @tiptap/cli@latest add docx ``` ### For new projects ```bash npx @tiptap/cli@latest init docx ``` This template requires styling and configuration setup. ### Styling We stay unopinionated about styling frameworks, so you'll need to integrate it with your setup. Follow the [style setup guide](https://tiptap.dev/docs/ui-components/getting-started/style.md) to ensure the editor displays correctly. The template ships SCSS, so make sure `sass` (and `sass-embedded`) are available as dev dependencies in your project. ### Environment variables The DOCX Editor uses two cloud services: **Collaboration** (for real-time editing) and **Conversion** (for the PDF/Word preview). Provide values for the following variables. **Collaboration** - `NEXT_PUBLIC_TIPTAP_COLLAB_APP_ID` — your Collaboration (document server) App ID. - `NEXT_PUBLIC_TIPTAP_COLLAB_TOKEN` — a JWT for accessing Collaboration services. - `NEXT_PUBLIC_TIPTAP_COLLAB_DOC_PREFIX` — *(optional)* prefix prepended to every document name. - `NEXT_PUBLIC_USE_JWT_TOKEN_API_ENDPOINT` — *(production)* an API endpoint that returns a freshly signed JWT, instead of shipping a static token to the client. **Conversion (PDF / Word preview)** - `NEXT_PUBLIC_TIPTAP_CONVERSION_APP_ID` — your Conversion App ID (read on the client and passed to the PDF exporter). - `TIPTAP_CONVERSION_SECRET` — *(server only)* the Conversion secret used by the `/api/convert/token` route to sign a short-lived (10 minute) JWT for the preview. The `NEXT_PUBLIC_`-prefixed variables must be available on the client. Depending on your framework, use the matching prefix: - [Next.js](https://tiptap.dev/docs/ui-components/install/next.md): `NEXT_PUBLIC_`. For example, `NEXT_PUBLIC_TIPTAP_COLLAB_APP_ID`. - [Vite + React](https://tiptap.dev/docs/ui-components/install/vite.md): `VITE_`. For example, `VITE_TIPTAP_COLLAB_APP_ID`. - Other frameworks: follow your framework's rules and wire the values into `tiptap-collab-utils.ts`. > **Generate the JWT:** > > To get started quickly, you can use the example JWTs from your Tiptap Cloud account and store them > in the token environment variables. Example JWTs are valid for a short time and should not be used > in production. In production, implement an API endpoint that generates JWTs on the server side. > See the full guide on [JWT authentication](https://tiptap.dev/docs/guides/authentication.md). If Collaboration is not configured, the editor renders a setup notice prompting you to set the App ID and token (or the JWT endpoint). You can also append `?noCollab=1` to the URL to disable collaboration for local testing. ## Usage Render the `PageDocxEditor` component. Each document is a collaborative room, so pass a unique `room` ID per document. ```tsx import { PageDocxEditor } from '@/components/tiptap-templates/page-docx/components/page-docx-editor' import initialContent from '@/components/tiptap-templates/page-docx/data/content.json' export default function App() { return } ``` ### Routing The template ships with a page that mirrors how the demo runs: visiting `/docx` redirects to `/docx/` with a freshly generated room ID, and the `[slug]` route renders the editor for that room while preloading the Google Fonts used by the font picker. Each room is a separate, persisted collaborative document. ### Props The exported `PageDocxEditor` component accepts: | Prop | Type | Description | | ----------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `room` | `string` | Collaboration room ID. Each document should use a unique room. If omitted, a random room is created. | | `initialContent` | `JSONContent` | Tiptap JSON seeded into the document the first time the room is opened. The template ships a sample NDA. Seeding is guarded so it never duplicates. | | `invertMenu` | `boolean` | Renders the toolbar at the bottom of the screen instead of the top. Can also be toggled with the `?menu=invert` query parameter. Defaults to `false`. | | `settingsStorage` | `SettingsStorage` | Persistence backend for sidebar UI settings (page format, header/footer settings, preview toggle). Defaults to a localStorage adapter. See [Settings persistence](#settings-persistence). | ## Features A fully paginated document editor with a Word-like toolbar, document settings, and live export. - **Pagination**: Content flows across real pages with configurable size, orientation, and margins. - **Headers and footers**: Editable per-document, with different first page and different odd/even variants, adjustable distance from the page edge, and dynamic page-number fields. - **Footnotes**: Word-like footnotes—references in the body, content in a per-page area above the footer, edited in an automatically-numbered overlay. - **Manual page breaks**: Insert a break that consumes the remaining page space and pushes following content to the next page, exactly like Word. - **Document settings**: Page size (20+ presets plus custom), orientation, margins, units, page gap, and page background color. - **Zoom & fit-to-page**: 40%–200% presets with an automatic fit-to-page mode that scales the page to the available width. - **Font family**: A categorized, searchable font picker. Carlito (a Calibri-compatible metric match) is the default and the embedded export font. - **Ordered-list numbering**: Eight numbering schemes (decimal, alpha, roman, nested, and more) that stay identical on screen and in the exported document. - **Rich text formatting**: Headings, bold/italic/strike/code, text color, links, inline images, bullet lists, line spacing, text alignment, and font size. - **DOCX export**: One-click download of a real `.docx` file, generated entirely in the browser. - **Live Word preview**: A side-by-side PDF rendering of the document as Word would lay it out, refreshable on demand. - **Real-time collaboration**: Live multi-user editing of the body, headers, footers, and footnotes with presence carets. - **Dark and light mode**: Fully themed out of the box. - **Responsive design**: A mobile layout with a full-screen preview mode and an overflowing toolbar that collapses extra controls into a menu. ### Pagination and page format The page geometry is owned by the Pages extension and configured from the document-settings sidebar. You can set: - **Page size** — A4, A5, A6, JIS B5, US Letter, US Legal, Executive, postcards, envelopes, and more, plus a **Custom** size with explicit width and height. - **Orientation** — portrait or landscape. - **Margins** — top, bottom, left, and right, with an optional “link margins” toggle that keeps all four in sync. - **Unit** — `cm`, `in`, `mm`, or `px`; all inputs reformat to the selected unit. - **Page gap** — the space between pages in the editor canvas. - **Page background color** — a transparent default plus a palette of preset colors. Settings entered in the sidebar drive the live editor; conversely, changes made through the Pages extension (including remote changes from a collaborator) flow back into the sidebar and persisted settings. ### Headers and footers Double-click any header or footer zone—or open the **Headers & footers** tab in the sidebar—to edit it in an overlay pinned over the live page. The sample document ships a header (document title + logo) and a footer (label, “Confidential”, and a `{page} of {pages}` field) laid out in tables. Supported options: - **Different first page** — a distinct header/footer on page 1. - **Different odd & even pages** — alternating headers/footers for book-style layouts. - **Distance to page edge** — header distance from the top and footer distance from the bottom, in the document's unit (clamped to Word's range, defaulting to \~1.25 cm). - **Page numbers** — insert a current-page or total-pages field. These render as `{page}` / `{pages}` tokens in the editor and become live Word fields on export. Because Pages keeps a separate inner editor per variant (default / first / odd / even), the sidebar includes a small pager to step between the reachable variants for the current document. ### Footnotes Footnotes are a feature of the Pages extension. Insert one from the toolbar (or with the keyboard shortcut) and a numbered reference is placed in the body while the footnote content opens in an overlay editor; the rendered footnote sits in a dedicated area above the footer on its page. On export, the DOCX exporter extracts these into real Word footnotes automatically. ### Page breaks A manual page break always leaves an empty paragraph before the break and drops the caret into a paragraph after it—matching how Word treats a manual break. Backspacing from that trailing empty paragraph deletes adjacent page breaks one at a time before falling back to normal editing. Insert a break from the toolbar or with `Mod-Enter`. ### Zoom The zoom control offers presets from 40% to 200% plus a **Fit to page** action. By default the editor is in an automatic mode that scales the page down to fit the available column width and back up to 100% as the viewport grows; choosing a preset switches to a fixed manual zoom. Zoom is published as a `--zoom` CSS variable so portalled overlays (such as the header/footer editors) scale consistently. ### Export and preview - **DOCX export** downloads a `.docx` file built in the browser by the Export DOCX extension—no server round-trip. Page size, margins (including header/footer expansion), background color, ordered-list numbering, and page-number fields are all carried into the document, the Carlito font is embedded, and editor CSS-variable colors are normalized to fixed hex values so the file looks the same everywhere. - **Word preview** is an on-demand PDF rendering of the same document, shown beside the editor (and full-screen on mobile). It is generated through the Tiptap Conversion API using a short-lived token from the `/api/convert/token` route, then rendered with `react-pdf`. The preview refreshes when you open it, when the page layout changes, and via an **Update preview** button when the document has unsaved changes. ### Real-time collaboration The body binds to a `TiptapCollabProvider` document, and each header/footer variant and the footnotes story sync through their own collaborative fields. Presence carets are shown for the body only (the inner editors intentionally forward content sync but not carets, to avoid duplicate cursors across the shared provider). The default header/footer chrome and the initial body content are seeded once per room, gated on the provider being synced so a returning room keeps whatever was edited. ### Settings persistence Sidebar UI settings (page format, header/footer settings, and the preview toggle) are persisted per room. By default they are stored in `localStorage` under room-scoped keys. The backend is pluggable via the `settingsStorage` prop and a `SettingsStorage` adapter interface: ```ts interface SettingsStorage { get(key: string): T | null set(key: string, value: T): void remove(key: string): void } ``` Pass `noopStorage` to disable persistence entirely, or implement the interface to persist settings to your own backend (for example, a database keyed by document). ## Component breakdown The template is composed of its own components, hooks, and libraries on top of a set of shared Tiptap UI components. ### Template components - `page-docx-editor` — the root component: collaboration setup, the editor instance, layout, and effects. - `page-docx-main-toolbar` — the Word-like toolbar, with overflow handling. - `page-docx-header-footer-overlay` — the floating “edit” affordance over hovered header/footer zones. - `page-docx-pdf-preview` — the `react-pdf` Word preview pane. - `page-docx-loading-overlay`, `floating`, `theme-toggle` — supporting UI. - `sidebar/*` — the document and header/footer settings panels, footer pagination, and the settings-panel primitives. - `zoom-dropdown-menu`, `font-family-combobox`, `numbering-format-dropdown-menu` — the specialized toolbar controls. ### Hooks - `use-page-editor-state` — derives page state (active editor type, page count, current page, header/footer flags) from the Pages storage. - `use-zoom`, `use-auto-export`, `use-page-docx-export`, `use-page-docx-insert-actions` — zoom, dirty-tracking, the DOCX/PDF export actions, and the toolbar insert actions (footnote / page break / image). - `use-overlay-focus`, `use-overlay-labels`, `use-mobile-typography-guard` — overlay behavior and layout helpers. Live element-rect tracking comes from the shared `use-bounding-rect` hook. ### Lib - `page-docx-utils`, `page-docx-pages` — units/conversions, page-format helpers, and settings sync. - `page-docx-export`, `page-docx-export-colors`, `page-docx-fonts` — export layout/styles, color normalization, and the font registry. - `settings-storage`, `settings-storage-context` — the pluggable persistence adapter and its React context. ### Extensions and workarounds - `extensions/extension-page-token-highlight` — the inline `{page}` / `{pages}` page-number node and its DOCX adapter. - `workaround/page-break`, `workaround/header-footer`, `workaround/footnote` — small, well-commented patches that make the Pages interactions (caret placement, overlay focus and scroll, footnote scroll-into-view) behave like a desktop word processor. ### Tiptap Pro extensions - `@tiptap-pro/extension-pages` - `@tiptap-pro/extension-convert-kit` - `@tiptap-pro/extension-export-docx` - `@tiptap-pro/extension-export-pdf` - `@tiptap-pro/extension-pagebreak` - `@tiptap-pro/provider` ### Reused UI components The toolbar and sidebar reuse the open-source UI components, including `mark-button`, `list-button`, `heading-button` / `heading-dropdown-menu`, `text-button`, `font-size-dropdown-menu`, `line-spacing-dropdown-menu`, `text-align-dropdown-menu`, `color-text-popover`, and `link-popover`, plus the `button`, `card`, `combobox`, `dropdown-menu`, `popover`, `sidebar`, and `toolbar` primitives. ## License The DOCX Editor template uses Tiptap Pro extensions and requires an active **Team plan** (or higher) subscription. Usage is subject to the [Tiptap Pro License](https://tiptap.dev/pro-license) and [Terms of Service](https://tiptap.dev/terms-of-service). The open-source UI components it builds on remain MIT licensed.