Fit modes

Size pages to the available width, to the whole page, or to their true size, and switch to true size as soon as users zoom.

Basics

fitMode="width" scales pages to fill the width of the document area at the default scale.

import { PdfViewer } from '@kingtech/react-pdf-viewer'; export default function Demo() { // At the default scale the page fills the available width. return <PdfViewer source="/samples/letter-3pages.pdf" fitMode="width" />; }

Fitting applies only while the scale equals defaultScale. As soon as the user zooms, the page is shown at its true size and the document area scrolls. Reset zoom (0) to fit again.

Fit the whole page

fitMode="page" scales each page so it fits entirely, width and height, which suits slide decks and documents with mixed page sizes.

import { PdfViewer } from '@kingtech/react-pdf-viewer'; export default function Demo() { // Pages of different sizes each fit entirely inside the document area. return <PdfViewer source="/samples/mixed-sizes.pdf" fitMode="page" />; }

Shrink only, or true size

Without fitMode, a page wider than the document area is shrunk to fit but never enlarged (fitWidthAtDefaultScale, on by default). Turn it off to always show pages at their true size.

import { PdfViewer } from '@kingtech/react-pdf-viewer'; export default function Demo() { // Never shrink: 100% is always the page's true size, and wide pages scroll. return ( <PdfViewer source="/samples/mixed-sizes.pdf" defaultPage={3} fitWidthAtDefaultScale={false} /> ); }

Choosing a mode

You want	Use
Readable text on phones and in narrow columns	the default (shrink only)
Documents that use all the space you give them	`fitMode="width"`
Presentations, posters, mixed page sizes	`fitMode="page"`
Pixel-exact 100% (e.g. comparing prints)	`fitWidthAtDefaultScale={false}`

Customization

The size of the document area is set by CSS variables, so the same fit mode behaves differently in different layouts.

import { PdfViewer } from '@kingtech/react-pdf-viewer'; import type { CSSProperties } from 'react'; // Fit into a wider, shorter document area than the default. const style = { '--rpv-viewport-max-width': '900px', '--rpv-viewport-min-height': '360px', '--rpv-viewport-max-height': '360px', '--rpv-page-radius': '0px', } as CSSProperties; export default function Demo() { return ( <PdfViewer source="/samples/mixed-sizes.pdf" defaultPage={3} fitMode="page" style={style} /> ); }

See --rpv-viewport-max-width, --rpv-viewport-min-height and --rpv-viewport-max-height in the CSS variables reference and the customization guide.

Advanced / escape hatch

PdfPageCanvas takes a fit box ({ width, height, upscale }) so custom layouts can size pages to any container; see FitOptions.

Limitations

Fitting only happens at the default scale. A controlled scale that differs from defaultScale always shows true size. Workaround: set defaultScale to the value you control, or reset to it.
Page fit uses the document area’s height. Inline, that area is at most 800px tall (100% of the viewer in fullscreen), so a tall portrait page fits to that height. Workaround: set --rpv-viewport-max-height to the height you want to fill.

API

PdfViewerProps — Props for PdfViewer. Every piece of state supports the value / defaultValue / onChange trio.