PDF Viewer React component for Tailwind CSS v4
v1.1.0Updated in 1.5.0
A React PDF viewer on PDFium: sharp pages, search, thumbnails, rotation, and highlights with notes that export as real PDF annotations.
Scroll through the pages; only the ones on screen render, and zoomed-in pages paint in sharp tiles. 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 on every page, the counter reads 2 of 5, and Enter / Shift+Enter or the arrows step through them. Drag across text to select it and press Ctrl+C / ⌘C to copy; on a phone a swipe scrolls, and a long press selects the word under the finger and dragging extends it word by word. With highlighting on, a bar opens beside the selection (pinned to the bottom, or the top when the selection is down there, on a phone) with five colors, underline, strikethrough, Add note and Copy; Ctrl+Shift+H / ⇧⌘H highlights the selection, or toggles the Highlighter, in which whatever you select is marked as soon as you let go (Escape turns it off). Clicking a highlight opens its details (a bottom sheet on phones): change the color or style, add or edit the note (Ctrl+Enter / ⌘Enter saves, Escape closes without saving and focus returns), copy the text or delete it. Ctrl+Z / ⌘Z and Ctrl+Shift+Z / ⇧⌘Z undo and redo. The Highlights panel lists every highlight with its page, text, note, author and date, filtered by color; a pick jumps to it and opens its details, Up and Down move through the list and Delete removes one. It sits beside the pages from 900px of width and slides over them below. Highlights also show on the thumbnails and follow zoom and rotation. The sidebar shows page thumbnails: click to jump, Shift+click for a range, Ctrl/⌘+click to add a page; in the list Up / Down move, Home / End jump, Shift extends and Space toggles. The rotate buttons turn the selected pages (or the current one) and the reading position holds. The ⋯ menu holds undo and redo, downloads the file (with your rotations, or with your highlights written in as annotations) and opens another PDF, which you can also drop onto the viewer. Below 520px of width the sidebar starts closed and slides over the pages; below 600px the rotate buttons move into the ⋯ menu, and below 440px the Highlights toggle does too.
PDF 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 pdf-viewer, together with Button, Dropdown Menu, Popover, Tooltip, useControllableState and 4 more and the npm packages @embedpdf/core, @embedpdf/engines, @embedpdf/models, @embedpdf/plugin-document-manager, @embedpdf/plugin-interaction-manager, @embedpdf/plugin-render, @embedpdf/plugin-rotate, @embedpdf/plugin-scroll, @embedpdf/plugin-search, @embedpdf/plugin-selection, @embedpdf/plugin-thumbnail, @embedpdf/plugin-tiling, @embedpdf/plugin-viewport, @embedpdf/plugin-zoom, pdf-lib 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 pdf-viewerPDF 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 PdfViewer from @/components/ui/pdf-viewer.
import { useState } from "react"
import { PdfViewer, type PdfViewerHighlight } from "@/components/ui/pdf-viewer"
export function ContractReview() {
const [highlights, setHighlights] = useState<PdfViewerHighlight[]>([])
return (
<PdfViewer
src="/demo/service-agreement.pdf"
fileName="Master Services Agreement"
height="80dvh"
author="Emma Carter"
highlights={highlights}
onHighlightsChange={setHighlights}
onActivePageChange={(page) => console.log("reading page", page)}
/>
)
}Props
srcdefault"/demo/service-agreement.pdf"stringURL of the PDF: same origin, a CORS-enabled URL or a blob: URL. Empty shows the open-a-PDF state. The playground value is the sample contract.
fileNamedefault""stringName used for downloads. 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.
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.
activeHighlightColordefault"rgba(249, 115, 22, 0.55)"stringFill of the current search hit.
selectionColordefault"rgba(59, 130, 246, 0.18)"stringFill drawn over selected text.
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.
showRotateControlsdefaulttruebooleanThe rotate buttons (in the ⋯ menu when the viewer is narrow).
showDownloaddefaulttruebooleanDownload in the ⋯ menu. Pages you rotated are saved rotated.
showUploaddefaulttruebooleanOpen a PDF in the ⋯ menu and dropping a PDF onto the viewer. The file opens locally; onPdfUpload hands it to you.
highlightingdefaulttruebooleanLets readers mark text: the bar beside a selection, the Highlighter, Ctrl+Shift+H / ⇧⌘H, editing in the details popover and undo / redo. false makes the viewer read-only: highlights you pass (or that the file carries) still show and open with their notes.
authordefault""stringSigned on new highlights, shown in the panel and written into the exported PDF as the annotation author.
defaultHighlightColordefault"#FDE047"stringThe pen color the Highlighter and Ctrl+Shift+H / ⇧⌘H start with; the first of highlightColors when unset. Any CSS color; hex is written into the PDF exactly.
showHighlightsPaneldefaulttruebooleanThe Highlights panel and its toolbar toggle (shown once highlighting is on or there are highlights).
defaultHighlightsPanelOpendefaultfalsebooleanOpens with the Highlights panel showing. Use highlightsPanelOpen and onHighlightsPanelOpenChange to control it.
defaultHighlighterModedefaultfalsebooleanStarts in Highlighter mode: selected text is marked as soon as the pointer is released. Use highlighterMode and onHighlighterModeChange to control it.
importHighlightsdefaulttruebooleanHighlight, underline, strikeout and squiggly annotations already in the file load as highlights (squiggly becomes underline). They are replaced by the list on export, so one deleted here is gone from the file too.
highlightShortcutdefault"shift+mod+h"stringHighlights the selection, or toggles the Highlighter, while focus is inside the viewer. mod is ⌘ on Apple devices and Ctrl elsewhere; empty turns it off.
localedefault""stringLocale of the dates in the Highlights panel and details. Empty uses the UIProvider locale, then the browser's.
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.
highlightsPdfViewerHighlight[]Controlled highlights: { id, page, rects, text, color, type?, note?, author?, createdAt, updatedAt? }, with rects in PDF points from the top-left of the unrotated page. Serializable: store it as JSON and pass it back. Pair it with onHighlightsChange.
defaultHighlightsPdfViewerHighlight[]The starting highlights while uncontrolled. Opening another file starts from an empty list.
onHighlightsChange(highlights: PdfViewerHighlight[]) => voidCalled with the whole list after every add, change, removal, undo, redo and import.
onHighlightAdd(highlight: PdfViewerHighlight) => voidCalled once per highlight a reader (or ref.addHighlight) adds, and when undo or redo brings one back. Not called for highlights imported from the file.
onHighlightChange(highlight: PdfViewerHighlight, previous: PdfViewerHighlight) => voidCalled when a highlight's color, style or note changes.
onHighlightRemove(highlight: PdfViewerHighlight) => voidCalled when a highlight is deleted or an undo takes it away.
highlightColorsdefault"DEFAULT_PDF_VIEWER_HIGHLIGHT_COLORS"PdfViewerHighlightColor[]The colors of the selection bar, the details and the panel filter, as { value, label }: yellow, green, blue, pink and orange by default.
highlightsPanelOpenbooleanControls the Highlights panel.
onHighlightsPanelOpenChange(open: boolean) => voidCalled when the Highlights panel opens or closes.
highlighterModebooleanControls the Highlighter mode.
onHighlighterModeChange(on: boolean) => voidCalled when the Highlighter turns on or off.
zoomLevelsdefault"[0.1, 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, sign, approve.
wasmUrldefault"https://cdn.jsdelivr.net/npm/@embedpdf/pdfium@2.15.1/dist/pdfium.wasm"stringWhere the PDFium binary (about 4 MB, cached) is loaded from. Defaults to jsDelivr; copy node_modules/@embedpdf/pdfium/dist/pdfium.wasm into public/ and point here for a strict CSP or offline apps. Your CSP needs 'wasm-unsafe-eval' in script-src either way.
refRef<PdfViewerHandle> (a useRef object or an (handle) => void callback)scrollToPage(page), scrollToPageArea(page, { top, left }) in percent of the page, getViewportElement(), and for highlights addHighlight(input?) (without input it highlights the selection), updateHighlight(id, patch), removeHighlight(id), scrollToHighlight(id), getHighlights(), exportPdf(), undo() and redo().
renderPageOverlay(props: PdfViewerPageOverlayProps) => ReactNodeDraws on top of every page: citations, bounding boxes, comments, signature fields. Gets the page number, its size at the current zoom, the scale and the rotation; it rotates with the page, so boxes in percent always line up.
pageClassName(pageNumber: number) => (string | undefined)Extra classes per page, e.g. a ring around the page a citation points to.
onActivePageChange(pageNumber: number) => voidCalled with the page in view as you scroll or jump.
onDocumentLoadSuccess(numPages: number) => voidCalled when a document is ready, with its page count.
onDocumentLoadError(error: unknown) => voidCalled when a document cannot be fetched or parsed. The viewer shows the error state.
onPdfUpload(file: File) => voidCalled with the File someone opened or dropped, after the viewer shows it.
onPagePointerDown(event: PointerEvent<HTMLDivElement>, pageNumber: number) => voidPointer down on a page, for drawing boxes or placing fields. Gets the event and the page number.
onPagePointerMove(event: PointerEvent<HTMLDivElement>, pageNumber: number) => voidPointer move over a page.
onPagePointerUp(event: PointerEvent<HTMLDivElement>, pageNumber: number) => voidPointer up on a page.
onPagePointerCancel(event: PointerEvent<HTMLDivElement>, pageNumber: number) => voidPointer cancel on a page (a touch turned into a scroll).
labelsPartial<PdfViewerLabels>Every string, English by default (DEFAULT_PDF_VIEWER_LABELS): page, of, pageNumber, pagesSidebar, pages, pageLabel(page), rotateLeft, rotateRight, zoomIn, zoomOut, zoomLevel, fitPage, fitWidth, automatic, search, searchPlaceholder, searching, noResults, results(active, total), previousResult, nextResult, clearSearch, moreActions, download, upload, document, loading, error, engineError, emptyTitle, emptyDescription, dropHere, and for highlights highlighter, highlightStyle, highlight, underline, strikeout, highlightWith(color), addNote, note, notePlaceholder, saveNote, cancel, copyText, copied, deleteHighlight, highlights, closeHighlights, allColors, filterByColor, noHighlights, noHighlightsDescription, noHighlightsInColor, selectionActions, highlightDetails, highlightLabel(page, text), highlightAdded(page), highlightRemoved, highlightUpdated, undo, redo, undone, redone, nothingToUndo, downloadWithHighlights, highlighterOn, highlighterOff.
classNamesPartial<Record<"toolbar" | "sidebar" | "thumbnail" | "viewport" | "page" | "state" | "highlight" | "selectionBar" | "highlightsPanel", string>>Extra classes for the toolbar, the sidebar, each thumbnail, the scrolling viewport, each page, the loading / empty / error states, each highlight box on a page, the selection bar and the Highlights panel.
classNamestringExtra classes for the frame, merged last. Other div props are forwarded to it.
Parts
PdfViewerHandle
typeWhat the ref gets: scrollToPage(pageNumber, options?), scrollToPageArea(pageNumber, { top, left?, width?, height? }, options?) with the area in percent of the page, getViewportElement(), addHighlight(input?) → Promise<PdfViewerHighlight[]>, updateHighlight(id, patch), removeHighlight(id), scrollToHighlight(id, options?), getHighlights(), exportPdf() → Promise<Blob> (the PDF with every highlight as a /Highlight, /Underline or /StrikeOut annotation, rotations applied), undo() and redo().
PdfViewerHighlight
typeOne marked passage on one page: id, page (1-based), rects ({ x, y, width, height } in PDF points from the top-left of the unrotated page, one per line), text, color, type ('highlight' | 'underline' | 'strikeout'), note, author, createdAt and updatedAt (ISO). Plain JSON.
PdfViewerHighlightInput
typeWhat addHighlight takes: a PdfViewerHighlight whose id and createdAt are optional.
PdfViewerHighlightType
type"highlight" | "underline" | "strikeout".
PdfViewerHighlightRect
type{ x, y, width, height } in PDF points from the top-left of the unrotated page.
PdfViewerHighlightColor
typeA color of the palette: { value, label }.
DEFAULT_PDF_VIEWER_HIGHLIGHT_COLORS
constantThe default palette: Yellow #FDE047, Green #86EFAC, Blue #93C5FD, Pink #F9A8D4 and Orange #FDBA74.
PdfViewerPageOverlayProps
typeWhat renderPageOverlay receives: pageNumber, pageWidth and pageHeight at the current zoom, scale, and rotation in degrees.
PdfViewerZoom
typeA scale or "fit-page" | "fit-width" | "automatic".
PdfViewerLabels
typeThe shape of labels: every string the viewer renders.
DEFAULT_PDF_VIEWER_LABELS
constantThe English labels. Spread it to translate a few strings.
PDFIUM_WASM_URL
constantThe default wasmUrl: PDFium 2.15.1 on jsDelivr.
Examples
Controlled highlights
highlights and onHighlightsChange keep the list in your app; select text to add one, and the list scrolls the viewer with scrollToHighlight.
Export and import
ref.exportPdf() writes real /Highlight, /Underline and /StrikeOut annotations; reopening the file loads them back as highlights.
Highlighter mode
defaultHighlighterMode marks text as soon as it is selected, in green, signed by Emma Carter.
Highlights panel
Every highlight with its page, note and author, filtered by color; picking one jumps to it and opens its details.
Read-only review
highlighting={false}: the highlights show and open with their notes, but nothing can be changed. toolbarActions adds Share and Sign.
On a phone
Long-press a word to select it and drag to extend; the color bar pins to the bottom and details open in a sheet.
Citations
renderPageOverlay draws bounding boxes on the invoice; picking a field scrolls the viewer to it with scrollToPageArea.
Empty, open a file
Without src the viewer asks for a PDF: pick one or drop it onto the frame. Highlights already in the file load with it.
Dependencies
Files
- components/ui/pdf-viewer.tsx
FAQ
Is the React PDF Viewer component free?
The preview, props and docs are free; copying the source needs a Pro plan. See plans.
How do I install PDF Viewer?
Run npx wingo-ui@latest add pdf-viewer. It also adds the Wingo UI items it builds on (Button, Dropdown Menu, Popover, Tooltip, useControllableState and 4 more) and the npm packages @embedpdf/core, @embedpdf/engines, @embedpdf/models, @embedpdf/plugin-document-manager, @embedpdf/plugin-interaction-manager, @embedpdf/plugin-render, @embedpdf/plugin-rotate, @embedpdf/plugin-scroll, @embedpdf/plugin-search, @embedpdf/plugin-selection, @embedpdf/plugin-thumbnail, @embedpdf/plugin-tiling, @embedpdf/plugin-viewport, @embedpdf/plugin-zoom, pdf-lib and lucide-react. With shadcn, add the @wingo-ui registry with your API key, then run npx shadcn@latest add @wingo-ui/pdf-viewer.
How does PDF Viewer behave on phones?
Drag across text to select it and press Ctrl+C / ⌘C to copy; on a phone a swipe scrolls, and a long press selects the word under the finger and dragging extends it word by word.
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.