# DOCX Viewer

> A React Word (.docx) viewer with real pages, headers and footers, thumbnails, zoom, search, comments, tracked changes and download.

- 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-viewer`
- Docs: https://wingo-ui.com/components/docx-viewer

## Interaction

Scroll through the pages: each one is laid out like Word's, with its header, footer and page numbers, and a page that runs long is split at its paragraphs and table rows. Type a page number in the toolbar (Enter jumps, Up and Down step, Escape cancels). Zoom with - and +, or pick Automatic, Fit page, Fit width or a percentage from the zoom menu. Search opens from the toolbar or with Ctrl+F / ⌘F while focus is inside the viewer: hits are highlighted, the counter reads 2 of 5, and Enter / Shift+Enter or the arrows step through them. Comments show as cards beside the pages with the commented text highlighted; click a card or the highlighted text to pick it. When the viewer is too narrow for the cards, markers sit on the page edge and open the card in a popover (a bottom sheet on phones). The toolbar switches comments, tracked changes (insertions underlined in green, removals struck through in red) and dark pages on or off and downloads the original file; below 720px of width these move into the ⋯ menu, which also opens another .docx (you can drop one onto the viewer too). Pinch with two fingers, or Ctrl / ⌘ + scroll, to zoom around that point. The sidebar shows page thumbnails: click to jump; in the list Up / Down move, Home / End jump. It starts open beside the pages; below 520px of width it starts closed, slides over the pages when opened and closes after a pick; below 440px the zoom steps move into the ⋯ menu.

## Installation

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

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-viewer` (needs the @wingo-ui registry with your API key in components.json)

Files:

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

npm dependencies: `npm i docx-preview lucide-react`

Wingo UI dependencies (installed automatically):

- [Button](https://wingo-ui.com/components/button) ([Markdown](https://wingo-ui.com/components/button.md))
- [Dropdown Menu](https://wingo-ui.com/components/dropdown-menu) ([Markdown](https://wingo-ui.com/components/dropdown-menu.md))
- [Popover](https://wingo-ui.com/components/popover) ([Markdown](https://wingo-ui.com/components/popover.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))
- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))

## Usage

```tsx
import { DocxViewer } from "@/components/ui/docx-viewer"

export function ProposalPreview() {
  return (
    <DocxViewer
      src="/demo/project-proposal.docx"
      fileName="Riverside renovation proposal"
      height="80dvh"
      onDocumentLoadSuccess={({ numPages, outline }) => console.log(numPages, outline)}
    />
  )
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src?` | `string` | `"/demo/project-proposal.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 proposal. |
| `fileName?` | `string` | `""` | Name used for downloads and in the document's accessible label. Falls back to the last part of src; an uploaded file keeps its own name. |
| `defaultZoom?` | `number \| "fit-page" \| "fit-width" \| "automatic"` | `"automatic"` | The zoom the document opens at: a scale (1 is 100%) or a fit mode. Automatic fits the width up to 100%, so a page never opens blown up on a large screen or cut off on a phone. |
| `defaultCommentsVisible?` | `boolean` | `true` | Opens with the comments showing: cards beside the pages, or markers on the page edge in a narrow viewer. |
| `defaultChangesVisible?` | `boolean` | `false` | Opens with tracked changes marked up (insertions underlined, removals struck through) and listed beside the pages. Off shows the document as it reads with every change accepted. |
| `defaultDarkPages?` | `boolean` | `false` | Opens with the pages inverted for reading at night; images keep their colors. Pages are white otherwise, in both themes. |
| `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.4)"` | Fill of every search hit. Any CSS color; keep it translucent so the text stays readable. Also set as --docx-viewer-highlight on the frame. |
| `activeHighlightColor?` | `string` | `"rgba(249, 115, 22, 0.55)"` | Fill of the current search hit and of the text behind the picked comment (--docx-viewer-active-highlight). |
| `commentHighlightColor?` | `string` | `"rgba(250, 204, 21, 0.28)"` | Fill of commented text while comments are showing (--docx-viewer-comment-highlight). |
| `showToolbar?` | `boolean` | `true` | The toolbar with page, zoom, search and file controls. Off leaves the bare pages, for previews you drive yourself. |
| `showThumbnails?` | `boolean` | `true` | The pages sidebar and its toggle. |
| `defaultSidebarOpen?` | `boolean` | `true` | Opens with the pages sidebar showing beside the pages. A viewer narrower than 520px (a phone) starts closed, since there the sidebar covers the page. Use sidebarOpen and onSidebarOpenChange to control it. |
| `showSearch?` | `boolean` | `true` | The search button, and Ctrl+F / ⌘F inside the viewer. |
| `showComments?` | `boolean` | `true` | Comments at all, and their switch in the toolbar (the ⋯ menu when narrow). |
| `showChanges?` | `boolean` | `true` | The tracked changes switch in the toolbar (the ⋯ menu when narrow). |
| `showDarkPages?` | `boolean` | `true` | The dark pages switch in the toolbar (the ⋯ menu when narrow). |
| `showDownload?` | `boolean` | `true` | The download button (in the ⋯ menu when narrow). It saves the original file. |
| `showUpload?` | `boolean` | `true` | Open a document in the ⋯ menu and dropping a .docx onto the viewer. The file opens locally; onDocxUpload hands it to you. |
| `height?` | `number \| string` | `640` | Height of the viewer: px as a number, or any CSS length ("100%", "80dvh") to fill a pane. |
| `sidebarOpen?` | `boolean` |  | Controls the pages sidebar. Inline from 520px of viewer width, an overlay below it. |
| `onSidebarOpenChange?` | `(open: boolean) => void` |  | Called when the sidebar opens or closes. |
| `zoomLevels?` | `number[]` | `"[0.25, 0.5, 0.75, 1, 1.25, 1.5, 2, 3, 4]"` | Steps of the zoom menu and the - / + buttons. The first and last are the zoom limits. |
| `toolbarActions?` | `ReactNode` |  | Your own buttons at the end of the toolbar, before the ⋯ menu: share, approve, send for signature. |
| `ref?` | `Ref<DocxViewerHandle> (a useRef object or an (handle) => void callback)` |  | scrollToPage(page), scrollToHeading(id), scrollToAnnotation(id), getOutline() and getViewportElement(). |
| `renderPageOverlay?` | `(props: DocxViewerPageOverlayProps) => ReactNode` |  | Draws on top of every page: stamps, citations, signature fields. Gets the page number, its size at the current zoom and the scale, so boxes in percent always line up. |
| `onActivePageChange?` | `(pageNumber: number) => void` |  | Called with the page in view as you scroll or jump. |
| `onDocumentLoadSuccess?` | `(document: DocxViewerDocument) => void` |  | Called when a document is ready, with its page count, its outline (the headings, for a table of contents) and its comments and tracked changes. |
| `onDocumentLoadError?` | `(error: unknown) => void` |  | Called when a document cannot be fetched or parsed. The viewer shows the error state. |
| `onDocxUpload?` | `(file: File) => void` |  | Called with the File someone opened or dropped, after the viewer shows it. |
| `onAnnotationClick?` | `(annotation: DocxViewerAnnotation) => void` |  | Called when a comment or change is picked, from its card, its marker or its text. |
| `labels?` | `Partial<DocxViewerLabels>` |  | Every string, English by default (DEFAULT_DOCX_VIEWER_LABELS): page, of, pageNumber, pagesSidebar, pages, pageLabel(page), zoomIn, zoomOut, zoomLevel, fitPage, fitWidth, automatic, search, searchPlaceholder, searching, noResults, results(active, total), previousResult, nextResult, clearSearch, moreActions, comments, changes, darkPages, download, upload, document, loading, error, emptyTitle, emptyDescription, dropHere, annotations, comment, inserted, deleted, unknownAuthor, annotationLabel(kind, author). |
| `classNames?` | `Partial<Record<"toolbar" \| "sidebar" \| "thumbnail" \| "viewport" \| "annotation" \| "state", string>>` |  | Extra classes for the toolbar, the sidebar, each thumbnail, the scrolling viewport, each comment card and the loading / empty / error states. |
| `className?` | `string` |  | Extra classes for the frame, merged last. Other div props are forwarded to it. |

## Parts

### DocxViewerHandle (type)

What the ref gets: scrollToPage(pageNumber, options?), scrollToHeading(id, options?) with an id from the outline, scrollToAnnotation(id, options?), getOutline() and getViewportElement().

### DocxViewerDocument (type)

What onDocumentLoadSuccess receives: numPages, outline (DocxViewerHeading[]) and annotations (DocxViewerAnnotation[]).

### DocxViewerHeading (type)

An outline entry: id, title, level (1 for Heading 1) and pageNumber.

### DocxViewerAnnotation (type)

A comment or tracked change: id, kind ("comment" | "insertion" | "deletion"), author, initials, date, text, anchorText (the commented passage) and pageNumber.

### DocxViewerPageOverlayProps (type)

What renderPageOverlay receives: pageNumber, pageWidth and pageHeight at the current zoom, and scale.

### DocxViewerZoom (type)

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

### DocxViewerLabels (type)

The shape of labels: every string the viewer renders.

### DEFAULT_DOCX_VIEWER_LABELS (constant)

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

## Examples

- **Comments and tracked changes**: Comments and edits from the file sit beside the pages; onAnnotationClick reports the one you pick.
- **Outline and page tracking**: onDocumentLoadSuccess hands over the headings, ref.scrollToHeading jumps to one and onActivePageChange follows the reader.
- **Sidebar closed**: defaultSidebarOpen={false} starts with the pages only, at fit width; the toolbar button brings the thumbnails back.
- **Approve with your own actions**: toolbarActions adds Share and Approve, and renderPageOverlay stamps the first page once it is approved.
- **On a phone**: The sidebar slides over the page, comments become markers that open a bottom sheet and the toolbar stays on one row.
- **Dark pages**: defaultDarkPages inverts the pages for night reading while images keep their colors.
- **Empty, open a file**: Without src the viewer asks for a .docx: pick one or drop it onto the frame.

## See also

- [DOCX Editor](https://wingo-ui.com/components/docx-editor) ([Markdown](https://wingo-ui.com/components/docx-editor.md))
- [PDF Viewer](https://wingo-ui.com/components/pdf-viewer) ([Markdown](https://wingo-ui.com/components/pdf-viewer.md))
- [PowerPoint Viewer](https://wingo-ui.com/components/pptx-viewer) ([Markdown](https://wingo-ui.com/components/pptx-viewer.md))
- [File Upload](https://wingo-ui.com/components/file-upload) ([Markdown](https://wingo-ui.com/components/file-upload.md))
- [File manager](https://wingo-ui.com/components/file-manager) ([Markdown](https://wingo-ui.com/components/file-manager.md))

---

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