DOCX Viewer React component for Tailwind CSS v4
v1.0.0Added in 1.4.0
A React Word (.docx) viewer with real pages, headers and footers, thumbnails, zoom, search, comments, tracked changes and download.
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.
DOCX Viewer is a Pro React component in the React media components category, written in TypeScript for React 19 and Tailwind CSS v4. It installs as source with npx wingo-ui@latest add docx-viewer, together with Button, Dropdown Menu, Popover, Tooltip, useControllableState and 1 more and the npm packages docx-preview and lucide-react.
Add to a project
Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup
npx wingo-ui@latest add docx-viewerDOCX Viewer is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans
Usage
Import DocxViewer from @/components/ui/docx-viewer.
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
srcdefault"/demo/project-proposal.docx"stringURL 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.
fileNamedefault""stringName 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.
defaultZoomdefault"automatic"number | "fit-page" | "fit-width" | "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.
defaultCommentsVisibledefaulttruebooleanOpens with the comments showing: cards beside the pages, or markers on the page edge in a narrow viewer.
defaultChangesVisibledefaultfalsebooleanOpens 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.
defaultDarkPagesdefaultfalsebooleanOpens with the pages inverted for reading at night; images keep their colors. Pages are white otherwise, in both themes.
localedefault"en-US"stringLocale for the dates on comments and changes. Unset, it follows the UIProvider locale, then the browser's (en-US here).
variantdefault"surface""surface" | "outline" | "plain"surface is a raised panel, outline a bordered box, plain has no frame for app panes that bring their own.
radiusdefault"md""none" | "sm" | "md" | "lg"Corner radius of the frame: 0, 12, 16 or 24px.
highlightColordefault"rgba(250, 204, 21, 0.4)"stringFill of every search hit. Any CSS color; keep it translucent so the text stays readable. Also set as --docx-viewer-highlight on the frame.
activeHighlightColordefault"rgba(249, 115, 22, 0.55)"stringFill of the current search hit and of the text behind the picked comment (--docx-viewer-active-highlight).
commentHighlightColordefault"rgba(250, 204, 21, 0.28)"stringFill of commented text while comments are showing (--docx-viewer-comment-highlight).
showToolbardefaulttruebooleanThe toolbar with page, zoom, search and file controls. Off leaves the bare pages, for previews you drive yourself.
showThumbnailsdefaulttruebooleanThe pages sidebar and its toggle.
defaultSidebarOpendefaulttruebooleanOpens 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.
showSearchdefaulttruebooleanThe search button, and Ctrl+F / ⌘F inside the viewer.
showCommentsdefaulttruebooleanComments at all, and their switch in the toolbar (the ⋯ menu when narrow).
showChangesdefaulttruebooleanThe tracked changes switch in the toolbar (the ⋯ menu when narrow).
showDarkPagesdefaulttruebooleanThe dark pages switch in the toolbar (the ⋯ menu when narrow).
showDownloaddefaulttruebooleanThe download button (in the ⋯ menu when narrow). It saves the original file.
showUploaddefaulttruebooleanOpen a document in the ⋯ menu and dropping a .docx onto the viewer. The file opens locally; onDocxUpload hands it to you.
heightdefault640number | stringHeight of the viewer: px as a number, or any CSS length ("100%", "80dvh") to fill a pane.
sidebarOpenbooleanControls the pages sidebar. Inline from 520px of viewer width, an overlay below it.
onSidebarOpenChange(open: boolean) => voidCalled when the sidebar opens or closes.
zoomLevelsdefault"[0.25, 0.5, 0.75, 1, 1.25, 1.5, 2, 3, 4]"number[]Steps of the zoom menu and the - / + buttons. The first and last are the zoom limits.
toolbarActionsReactNodeYour own buttons at the end of the toolbar, before the ⋯ menu: share, approve, send for signature.
refRef<DocxViewerHandle> (a useRef object or an (handle) => void callback)scrollToPage(page), scrollToHeading(id), scrollToAnnotation(id), getOutline() and getViewportElement().
renderPageOverlay(props: DocxViewerPageOverlayProps) => ReactNodeDraws 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) => voidCalled with the page in view as you scroll or jump.
onDocumentLoadSuccess(document: DocxViewerDocument) => voidCalled 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) => voidCalled when a document cannot be fetched or parsed. The viewer shows the error state.
onDocxUpload(file: File) => voidCalled with the File someone opened or dropped, after the viewer shows it.
onAnnotationClick(annotation: DocxViewerAnnotation) => voidCalled when a comment or change is picked, from its card, its marker or its text.
labelsPartial<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).
classNamesPartial<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.
classNamestringExtra classes for the frame, merged last. Other div props are forwarded to it.
Parts
DocxViewerHandle
typeWhat the ref gets: scrollToPage(pageNumber, options?), scrollToHeading(id, options?) with an id from the outline, scrollToAnnotation(id, options?), getOutline() and getViewportElement().
DocxViewerDocument
typeWhat onDocumentLoadSuccess receives: numPages, outline (DocxViewerHeading[]) and annotations (DocxViewerAnnotation[]).
DocxViewerHeading
typeAn outline entry: id, title, level (1 for Heading 1) and pageNumber.
DocxViewerAnnotation
typeA comment or tracked change: id, kind ("comment" | "insertion" | "deletion"), author, initials, date, text, anchorText (the commented passage) and pageNumber.
DocxViewerPageOverlayProps
typeWhat renderPageOverlay receives: pageNumber, pageWidth and pageHeight at the current zoom, and scale.
DocxViewerZoom
typeA scale or "fit-page" | "fit-width" | "automatic".
DocxViewerLabels
typeThe shape of labels: every string the viewer renders.
DEFAULT_DOCX_VIEWER_LABELS
constantThe 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.
Dependencies
Files
- components/ui/docx-viewer.tsx
FAQ
Is the React DOCX Viewer component free?
The preview, props and docs are free; copying the source needs a Pro plan. See plans.
How do I install DOCX Viewer?
Run npx wingo-ui@latest add docx-viewer. It also adds the Wingo UI items it builds on (Button, Dropdown Menu, Popover, Tooltip, useControllableState and 1 more) and the npm packages docx-preview and lucide-react. With shadcn, add the @wingo-ui registry with your API key, then run npx shadcn@latest add @wingo-ui/docx-viewer.
How does DOCX Viewer behave on phones?
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).
See also
Used in
More React media components
Articles using this component
- React PPTX Viewer: Slides, Notes and Presenter Mode
Component guides9 min read
- React PDF Viewer: Search, Highlights, Real Annotations
Component guides9 min read
- React DOCX Viewer: Real Pages, Comments, Tracked Changes
Component guides9 min read
New components by email
New posts, product news and occasional offers from Wingo UI. We count clicks to keep it relevant.