# DOCX Editor

> A React Word (.docx) editor with real pages, styles, tables, images, find and replace, comments and tracked changes, saved as .docx.

- Type: React component (Media)
- Access: Pro (the source needs a Wingo UI Pro plan, see https://wingo-ui.com/pricing)
- Version: 1.0.0
- Install: `npx wingo-ui@latest add docx-editor`
- Docs: https://wingo-ui.com/components/docx-editor

## Interaction

Click on a page to place the caret and type; drag, double-click (word) or triple-click (paragraph) to select, Shift+click to extend. Arrow keys move by the lines you see on the page; Tab inserts a tab and Escape moves focus to the toolbars. The formatting bar sets the paragraph style (each style previews in a card), the font (the document's own fonts first), the size (type it, or A- / A+, Shift+Ctrl / ⇧⌘ + < >), bold, italic, underline, strikethrough, superscript, subscript, text color, highlight, links (Ctrl / ⌘+K opens a bar: Enter applies, Escape cancels), alignment, lists, indent (Ctrl / ⌘ + [ ]), line and paragraph spacing, images (pick or drop one, then drag a corner to resize), tables (a 10 x 8 grid; inside a table a menu adds, deletes, merges and splits), page breaks (Ctrl / ⌘+Enter), borders and clear formatting. What does not fit folds into the ⋯ menu; on a phone the bar sits at the bottom, above the keyboard. Ctrl / ⌘+F finds (Enter / Shift+Enter step, 2 of 6), Shift+Ctrl / ⇧⌘+H replaces one or all. Select text and add a comment (Ctrl+Alt / ⌥⌘+M): cards sit beside the pages where they fit, in a panel otherwise, with replies, resolve and reopen; tracked changes have Accept and Reject. The mode menu switches Editing, Suggesting (your edits become tracked changes under author) and Viewing. Zoom with - and +, the zoom menu (fit width, fit page), Ctrl / ⌘ + scroll, pinch, or Ctrl / ⌘ + = / -. The sidebar lists live page thumbnails (Up / Down, Home / End). Save (Ctrl / ⌘+S, with onSave), download, print (Ctrl / ⌘+P) and open another .docx from the toolbar; opening one over unsaved edits asks first.

## Installation

```bash
npx wingo-ui@latest add docx-editor
```

Pro item: run `npx wingo-ui@latest login` once with a Pro account. The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add @wingo-ui/docx-editor` (needs the @wingo-ui registry with your API key in components.json)

Files:

- `components/ui/docx-editor.tsx`

npm dependencies: `npm i @eigenpal/docx-editor-core prosemirror-state prosemirror-view prosemirror-model prosemirror-history prosemirror-tables jszip lucide-react`

Wingo UI dependencies (installed automatically):

- [Alert Dialog](https://wingo-ui.com/components/alert-dialog) ([Markdown](https://wingo-ui.com/components/alert-dialog.md))
- [Button](https://wingo-ui.com/components/button) ([Markdown](https://wingo-ui.com/components/button.md))
- [Color Picker](https://wingo-ui.com/components/color-picker) ([Markdown](https://wingo-ui.com/components/color-picker.md))
- [Dropdown Menu](https://wingo-ui.com/components/dropdown-menu) ([Markdown](https://wingo-ui.com/components/dropdown-menu.md))
- [Kbd](https://wingo-ui.com/components/kbd) ([Markdown](https://wingo-ui.com/components/kbd.md))
- [Popover](https://wingo-ui.com/components/popover) ([Markdown](https://wingo-ui.com/components/popover.md))
- [Select](https://wingo-ui.com/components/select) ([Markdown](https://wingo-ui.com/components/select.md))
- [Tooltip](https://wingo-ui.com/components/tooltip) ([Markdown](https://wingo-ui.com/components/tooltip.md))
- [useControllableState](https://wingo-ui.com/components/use-controllable-state) ([Markdown](https://wingo-ui.com/components/use-controllable-state.md))
- [useMediaQuery](https://wingo-ui.com/components/use-media-query) ([Markdown](https://wingo-ui.com/components/use-media-query.md))
- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))

## Usage

```tsx
import { useRef } from "react"
import { DocxEditor, type DocxEditorHandle } from "@/components/ui/docx-editor"

export function AgreementEditor() {
  const editor = useRef<DocxEditorHandle>(null)
  return (
    <DocxEditor
      ref={editor}
      src="/demo/northwind-supply-agreement.docx"
      author="Emma Carter"
      height="80dvh"
      onSave={async (blob, { fileName }) => {
        const body = new FormData()
        body.append("file", blob, fileName)
        await fetch("/api/documents", { method: "POST", body })
      }}
      onDirtyChange={(dirty) => console.log(dirty ? "Unsaved changes" : "Saved")}
    />
  )
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src?` | `string` | `"/demo/northwind-supply-agreement.docx"` | URL of the .docx: same origin, a CORS-enabled URL or a blob: URL. Empty shows the open-a-document state. The playground value is the sample agreement. |
| `fileName?` | `string` | `""` | Name for downloads, onSave and the document's accessible label. Falls back to the last part of src or the opened file's name. |
| `author?` | `string` | `"You"` | The name on comments you add and on suggestions made in Suggesting mode; its initials sit in the status bar. |
| `defaultReadOnly?` | `boolean` | `false` | Opens in view-only mode: no caret, no formatting bar; Download and Print still work. The mode menu can switch back. Use readOnly to control it. |
| `defaultSuggesting?` | `boolean` | `false` | Opens in Suggesting mode: insertions and deletions become tracked changes by author. Use suggesting to control it. |
| `dirty?` | `boolean` | `false` | Adds your own unsaved state to the status bar. Switching it from true to false after you stored ref.exportDocx() marks the content as saved. |
| `defaultZoom?` | `number \| "fit-page" \| "fit-width" \| "automatic"` | `"automatic"` | The zoom each document opens at: a scale (1 is 100%) or a fit mode. Automatic fits the width up to 100%, so a phone shows the whole page width. |
| `defaultSidebarOpen?` | `boolean` | `true` | Opens with the page thumbnails beside the pages. An editor narrower than 520px starts closed, since there the sidebar covers the page. |
| `defaultDarkPages?` | `boolean` | `false` | Opens with the pages inverted for reading at night; images keep their colors. Pages are white otherwise, in both themes. |
| `webFonts?` | `boolean` | `false` | Loads metric-compatible fonts (Carlito for Calibri, Caladea for Cambria) from Google Fonts for closer line breaks. Off by default: no third-party requests. |
| `locale?` | `string` | `"en-US"` | Locale for the dates on comments and changes. Unset, it follows the UIProvider locale, then the browser's (en-US here). |
| `variant?` | `"surface" \| "outline" \| "plain"` | `"surface"` | surface is a raised panel, outline a bordered box, plain has no frame for app panes that bring their own. |
| `radius?` | `"none" \| "sm" \| "md" \| "lg"` | `"md"` | Corner radius of the frame: 0, 12, 16 or 24px. |
| `highlightColor?` | `string` | `"rgba(250, 204, 21, 0.45)"` | Fill of every find hit (--docx-editor-highlight). Keep it translucent so the text stays readable. |
| `activeHighlightColor?` | `string` | `"rgba(249, 115, 22, 0.5)"` | Fill of the current find hit and of text waiting for a new comment (--docx-editor-active-highlight). |
| `selectionColor?` | `string` | `"rgba(59, 130, 246, 0.28)"` | The text selection drawn on the page (--docx-editor-selection). |
| `showToolbar?` | `boolean` | `true` | The document toolbar: thumbnails, page, mode, zoom, find, view switches, save and the ⋯ menu. |
| `showFormatBar?` | `boolean` | `true` | The formatting bar. Hidden in view-only mode; below 600px of width it moves to the bottom, above the keyboard. |
| `showThumbnails?` | `boolean` | `true` | The page thumbnails sidebar and its toggle. |
| `showStatusBar?` | `boolean` | `true` | The bottom line with the page, the word count, the mode and the saved state. |
| `showComments?` | `boolean` | `true` | Comment cards, Add comment and their switch. |
| `showChanges?` | `boolean` | `true` | Tracked change cards with Accept / Reject, their switch and Suggesting in the mode menu. |
| `showDarkPages?` | `boolean` | `true` | The dark pages switch (in the ⋯ menu when narrow). |
| `showFind?` | `boolean` | `true` | Find and replace, and Ctrl / ⌘+F inside the editor. |
| `showImport?` | `boolean` | `true` | Open a document and New blank document in the ⋯ menu, and dropping a .docx onto the editor (not in view-only mode). |
| `showDownload?` | `boolean` | `true` | Download .docx with your edits (in the ⋯ menu when narrow). |
| `showPrint?` | `boolean` | `true` | Print in the ⋯ menu and Ctrl / ⌘+P inside the editor. |
| `showReadOnlyToggle?` | `boolean` | `true` | Viewing in the mode menu, so people can switch to view-only themselves. |
| `height?` | `number \| string` | `640` | Height of the editor: px as a number, or any CSS length ("100%", "80dvh") to fill a pane. |
| `file?` | `File \| Blob \| ArrayBuffer` |  | A document you already hold in memory; wins over src. A new object opens a new document. |
| `readOnly?` | `boolean` |  | Controls view-only mode: no caret, no formatting bar, Download and Print still work. Pair it with onReadOnlyChange so the mode menu can switch it. |
| `onReadOnlyChange?` | `(readOnly: boolean) => void` |  | Called when the mode menu or ref.setReadOnly switches view-only mode. |
| `suggesting?` | `boolean` |  | Controls Suggesting mode. Pair it with onSuggestingChange so the mode menu can switch it. |
| `onSuggestingChange?` | `(suggesting: boolean) => void` |  | Called when the mode menu switches Suggesting on or off. |
| `zoomLevels?` | `number[]` | `"[0.5, 0.75, 0.9, 1, 1.1, 1.25, 1.5, 1.75, 2]"` | Steps of the zoom menu and the - / + buttons. The first and last are the zoom limits. |
| `sidebarOpen?` | `boolean` |  | Controls the thumbnails sidebar. Inline from 520px of editor width, an overlay below it. |
| `onSidebarOpenChange?` | `(open: boolean) => void` |  | Called when the sidebar opens or closes. |
| `onDirtyChange?` | `(dirty: boolean) => void` |  | Called when the document gets unsaved edits, and again when they are saved or undone. |
| `onChange?` | `(details: DocxEditorChangeDetails) => void` |  | Called 400 ms after the last edit, with the page count, word count and dirty flag. Get the file with ref.exportDocx(). |
| `onSave?` | `(blob: Blob, info: DocxEditorSaveInfo) => (void \| Promise<unknown>)` |  | Shows a Save button and binds Ctrl / ⌘+S. Gets the .docx and its file name, page and word counts. Return a promise to show Saving and then Saved, or the error. |
| `onDocumentLoadSuccess?` | `(document: DocxEditorDocument) => void` |  | Called when a document is ready, with its page and word counts, comments and tracked changes. |
| `onDocumentLoadError?` | `(error: unknown) => void` |  | Called when a document cannot be fetched or parsed. The editor shows the error state with Try again. |
| `onError?` | `(error: unknown) => void` |  | Called when an export, a save, an image or a layout pass fails. |
| `onDocxUpload?` | `(file: File) => void` |  | Called with the File someone opened or dropped. |
| `onActivePageChange?` | `(pageNumber: number) => void` |  | Called with the page in view as you scroll or jump. |
| `onCommentAdd?` | `(comment: DocxEditorComment) => void` |  | Called when someone adds a comment or a reply. |
| `onCommentResolve?` | `(comment: DocxEditorComment) => void` |  | Called when a comment is resolved. |
| `onChangeAccept?` | `(change: DocxEditorChange) => void` |  | Called when a tracked change is accepted. |
| `onChangeReject?` | `(change: DocxEditorChange) => void` |  | Called when a tracked change is rejected. |
| `toolbarActions?` | `ReactNode` |  | Your own buttons at the end of the toolbar, before the ⋯ menu: share, send for signature, publish. |
| `ref?` | `Ref<DocxEditorHandle> (a useRef object or an (handle) => void callback)` |  | exportDocx(), download(fileName?), getText(), insertText(text), focus(), undo(), redo(), scrollToPage(n), find(query), setReadOnly(readOnly), isDirty(), markSaved(), getPageCount() and getWordCount(). |
| `labels?` | `Partial<DocxEditorLabels>` |  | Every string, English by default (DEFAULT_DOCX_EDITOR_LABELS): toolbar and menu names, tooltips, find and replace, comments and changes, states, the discard dialog. Strings with numbers are functions, like findResults(active, total), wordCount(words) and tableSize(rows, columns). |
| `classNames?` | `Partial<Record<"toolbar" \| "formatBar" \| "sidebar" \| "thumbnail" \| "viewport" \| "page" \| "annotation" \| "statusBar" \| "findBar" \| "state", string>>` |  | Extra classes for the toolbar, the formatting bar, the sidebar, each thumbnail, the scrolling viewport, the pages, each card, the status bar, the find bar and the states. |
| `className?` | `string` |  | Extra classes for the frame, merged last. Other div props are forwarded to it. |

## Parts

### DocxEditorHandle (type)

What the ref gets: exportDocx(): Promise<Blob>, download(fileName?), getText(), insertText(text), focus(), undo(), redo(), scrollToPage(pageNumber), find(query) (opens find and returns the count), setReadOnly(readOnly), isDirty(), markSaved(), getPageCount() and getWordCount().

### DocxEditorDocument (type)

What onDocumentLoadSuccess receives: pageCount, wordCount, comments (DocxEditorComment[]) and changes (DocxEditorChange[]).

### DocxEditorComment (type)

A comment or reply: id, author, initials, date, text, anchorText (the commented passage), parentId (for replies) and resolved.

### DocxEditorChange (type)

A tracked change: id (the revision), kind ("insertion" | "deletion" | "replacement" | "formatting" | "structure"), author, date, text and deletedText.

### DocxEditorChangeDetails (type)

What onChange receives: pageCount, wordCount and dirty.

### DocxEditorSaveInfo (type)

The second argument of onSave: fileName, pageCount and wordCount.

### DocxEditorSource (type)

What file accepts: File | Blob | ArrayBuffer.

### DocxEditorZoom (type)

A scale or "fit-page" | "fit-width" | "automatic".

### DocxEditorMode (type)

"editing" | "suggesting" | "viewing", the three modes of the mode menu.

### DocxEditorLabels (type)

The shape of labels: every string the editor renders.

### DEFAULT_DOCX_EDITOR_LABELS (constant)

The English labels. Spread it to translate a few strings.

## Examples

- **Save with an unsaved indicator**: onSave adds Save and Ctrl / ⌘+S; onDirtyChange drives the indicator above the editor.
- **Read-only, unlocked from outside**: readOnly hides the formatting bar and the caret; Download and Print keep working.
- **Review: suggesting, comments, accept and reject**: defaultSuggesting tracks edits as author; cards beside the pages accept, reject, reply and resolve.
- **Start from a blank page**: Without src the editor offers to open a .docx or start a new blank document.
- **Your own toolbar actions, no sidebar**: toolbarActions adds Share and Send for signature; showThumbnails={false} drops the sidebar.
- **Export to a Blob through the ref**: ref.exportDocx() returns the edited .docx; its size, word and page counts show above.
- **On a phone**: One-row toolbars, formatting at the bottom above the keyboard, fit-width pages and sheets for menus.

## See also

- [DOCX Viewer](https://wingo-ui.com/components/docx-viewer) ([Markdown](https://wingo-ui.com/components/docx-viewer.md))
- [Rich Text Editor](https://wingo-ui.com/components/rich-text-editor) ([Markdown](https://wingo-ui.com/components/rich-text-editor.md))
- [PDF Viewer](https://wingo-ui.com/components/pdf-viewer) ([Markdown](https://wingo-ui.com/components/pdf-viewer.md))
- [File Upload](https://wingo-ui.com/components/file-upload) ([Markdown](https://wingo-ui.com/components/file-upload.md))

---

Canonical: https://wingo-ui.com/components/docx-editor
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt
