# PDF Viewer

> A React PDF viewer on PDFium: sharp pages, search, thumbnails, rotation, and highlights with notes that export as real PDF annotations.

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

## Interaction

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.

## Installation

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

Files:

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

npm dependencies: `npm i @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 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))
- [useMediaQuery](https://wingo-ui.com/components/use-media-query) ([Markdown](https://wingo-ui.com/components/use-media-query.md))
- [useShortcut](https://wingo-ui.com/components/use-shortcut) ([Markdown](https://wingo-ui.com/components/use-shortcut.md))
- [Motion presets](https://wingo-ui.com/components/motion) ([Markdown](https://wingo-ui.com/components/motion.md))
- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))

## Usage

```tsx
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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src?` | `string` | `"/demo/service-agreement.pdf"` | URL 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. |
| `fileName?` | `string` | `""` | Name used for downloads. 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. |
| `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. |
| `activeHighlightColor?` | `string` | `"rgba(249, 115, 22, 0.55)"` | Fill of the current search hit. |
| `selectionColor?` | `string` | `"rgba(59, 130, 246, 0.18)"` | Fill drawn over selected text. |
| `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. |
| `showRotateControls?` | `boolean` | `true` | The rotate buttons (in the ⋯ menu when the viewer is narrow). |
| `showDownload?` | `boolean` | `true` | Download in the ⋯ menu. Pages you rotated are saved rotated. |
| `showUpload?` | `boolean` | `true` | Open a PDF in the ⋯ menu and dropping a PDF onto the viewer. The file opens locally; onPdfUpload hands it to you. |
| `highlighting?` | `boolean` | `true` | Lets 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. |
| `author?` | `string` | `""` | Signed on new highlights, shown in the panel and written into the exported PDF as the annotation author. |
| `defaultHighlightColor?` | `string` | `"#FDE047"` | The 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. |
| `showHighlightsPanel?` | `boolean` | `true` | The Highlights panel and its toolbar toggle (shown once highlighting is on or there are highlights). |
| `defaultHighlightsPanelOpen?` | `boolean` | `false` | Opens with the Highlights panel showing. Use highlightsPanelOpen and onHighlightsPanelOpenChange to control it. |
| `defaultHighlighterMode?` | `boolean` | `false` | Starts in Highlighter mode: selected text is marked as soon as the pointer is released. Use highlighterMode and onHighlighterModeChange to control it. |
| `importHighlights?` | `boolean` | `true` | Highlight, 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. |
| `highlightShortcut?` | `string` | `"shift+mod+h"` | Highlights the selection, or toggles the Highlighter, while focus is inside the viewer. mod is ⌘ on Apple devices and Ctrl elsewhere; empty turns it off. |
| `locale?` | `string` | `""` | Locale of the dates in the Highlights panel and details. Empty uses the UIProvider locale, then the browser's. |
| `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. |
| `highlights?` | `PdfViewerHighlight[]` |  | 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. |
| `defaultHighlights?` | `PdfViewerHighlight[]` |  | The starting highlights while uncontrolled. Opening another file starts from an empty list. |
| `onHighlightsChange?` | `(highlights: PdfViewerHighlight[]) => void` |  | Called with the whole list after every add, change, removal, undo, redo and import. |
| `onHighlightAdd?` | `(highlight: PdfViewerHighlight) => void` |  | Called 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) => void` |  | Called when a highlight's color, style or note changes. |
| `onHighlightRemove?` | `(highlight: PdfViewerHighlight) => void` |  | Called when a highlight is deleted or an undo takes it away. |
| `highlightColors?` | `PdfViewerHighlightColor[]` | `"DEFAULT_PDF_VIEWER_HIGHLIGHT_COLORS"` | The colors of the selection bar, the details and the panel filter, as { value, label }: yellow, green, blue, pink and orange by default. |
| `highlightsPanelOpen?` | `boolean` |  | Controls the Highlights panel. |
| `onHighlightsPanelOpenChange?` | `(open: boolean) => void` |  | Called when the Highlights panel opens or closes. |
| `highlighterMode?` | `boolean` |  | Controls the Highlighter mode. |
| `onHighlighterModeChange?` | `(on: boolean) => void` |  | Called when the Highlighter turns on or off. |
| `zoomLevels?` | `number[]` | `"[0.1, 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, sign, approve. |
| `wasmUrl?` | `string` | `"https://cdn.jsdelivr.net/npm/@embedpdf/pdfium@2.15.1/dist/pdfium.wasm"` | Where 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. |
| `ref?` | `Ref<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) => ReactNode` |  | Draws 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) => void` |  | Called with the page in view as you scroll or jump. |
| `onDocumentLoadSuccess?` | `(numPages: number) => void` |  | Called when a document is ready, with its page count. |
| `onDocumentLoadError?` | `(error: unknown) => void` |  | Called when a document cannot be fetched or parsed. The viewer shows the error state. |
| `onPdfUpload?` | `(file: File) => void` |  | Called with the File someone opened or dropped, after the viewer shows it. |
| `onPagePointerDown?` | `(event: PointerEvent<HTMLDivElement>, pageNumber: number) => void` |  | Pointer down on a page, for drawing boxes or placing fields. Gets the event and the page number. |
| `onPagePointerMove?` | `(event: PointerEvent<HTMLDivElement>, pageNumber: number) => void` |  | Pointer move over a page. |
| `onPagePointerUp?` | `(event: PointerEvent<HTMLDivElement>, pageNumber: number) => void` |  | Pointer up on a page. |
| `onPagePointerCancel?` | `(event: PointerEvent<HTMLDivElement>, pageNumber: number) => void` |  | Pointer cancel on a page (a touch turned into a scroll). |
| `labels?` | `Partial<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. |
| `classNames?` | `Partial<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. |
| `className?` | `string` |  | Extra classes for the frame, merged last. Other div props are forwarded to it. |

## Parts

### PdfViewerHandle (type)

What 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 (type)

One 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 (type)

What 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 (type)

A color of the palette: { value, label }.

### DEFAULT_PDF_VIEWER_HIGHLIGHT_COLORS (constant)

The default palette: Yellow #FDE047, Green #86EFAC, Blue #93C5FD, Pink #F9A8D4 and Orange #FDBA74.

### PdfViewerPageOverlayProps (type)

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

### PdfViewerZoom (type)

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

### PdfViewerLabels (type)

The shape of labels: every string the viewer renders.

### DEFAULT_PDF_VIEWER_LABELS (constant)

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

### PDFIUM_WASM_URL (constant)

The 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.

## See also

- [DOCX Viewer](https://wingo-ui.com/components/docx-viewer) ([Markdown](https://wingo-ui.com/components/docx-viewer.md))
- [PowerPoint Viewer](https://wingo-ui.com/components/pptx-viewer) ([Markdown](https://wingo-ui.com/components/pptx-viewer.md))
- [CSV Viewer](https://wingo-ui.com/components/csv-viewer) ([Markdown](https://wingo-ui.com/components/csv-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))
- [Image Lightbox](https://wingo-ui.com/components/image-lightbox) ([Markdown](https://wingo-ui.com/components/image-lightbox.md))

---

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