DOCX Editor

Available in Team plan

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 extension and the Conversion DOCX/PDF exporters, with real-time collaboration provided by Tiptap Collaboration.

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 and Pro License.

Overview

The template combines several Tiptap Pro extensions into a single document-editing experience:

Pages — pagination, page format (size, orientation, margins), headers and footers, footnotes, and zoom.
Convert / Export DOCX — turns the editor document into a real Word .docx file in the browser.
Export PDF — generates the side-by-side Word preview through the Tiptap Conversion API.
Collaboration — 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.

For existing projects

npx @tiptap/cli@latest add docx

For new projects

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 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: NEXT_PUBLIC_. For example, NEXT_PUBLIC_TIPTAP_COLLAB_APP_ID.
Vite + React: 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.

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.

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 <PageDocxEditor room="contract-123" initialContent={initialContent} />
}

Routing

The template ships with a page that mirrors how the demo runs: visiting /docx redirects to /docx/<room-id> 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.

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:

interface SettingsStorage {
  get<T = unknown>(key: string): T | null
  set<T = unknown>(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 and Terms of Service. The open-source UI components it builds on remain MIT licensed.

PreviouslyNotion Editor

Next upOverview