Controlled state

Own the page, zoom, rotation and fullscreen state in your app, or let the viewer keep it, with one consistent pattern.

Every piece of viewer state follows the same trio: x controls the value, defaultX sets its initial value while uncontrolled, and onXChange reports every change in both modes.

State	Controlled	Initial	Change
Page	`page`	`defaultPage`	`onPageChange`
Zoom	`scale`	`defaultScale`	`onScaleChange`
Rotation	`rotation`	`defaultRotation`	`onRotationChange`
Fullscreen	`fullscreen`	`defaultFullscreen`	`onFullscreenChange`

Basics

Pass a value and its change handler to put that state in your app.

import { PdfViewer, type Rotation } from '@kingtech/react-pdf-viewer'; import { useState } from 'react'; export default function Demo() { const [page, setPage] = useState(1); const [scale, setScale] = useState(1); const [rotation, setRotation] = useState<Rotation>(0); return ( <> <p className="demo-controls"> <button type="button" className="demo-button" onClick={() => setPage(99)}> Go to page 99 </button> <button type="button" className="demo-button" onClick={() => setScale((s) => Math.min(5, s + 0.25))} > Zoom +25% </button> <button type="button" className="demo-button" onClick={() => { setPage(1); setScale(1); setRotation(0); }} > Reset </button> <output> page {page} · {Math.round(scale * 100)}% · {rotation}° </output> </p> <PdfViewer source="/samples/multipage.pdf" page={page} onPageChange={setPage} scale={scale} onScaleChange={setScale} rotation={rotation} onRotationChange={setRotation} /> </> ); }

The toolbar and keyboard keep working: they call your handlers, and the viewer shows whatever you pass back. Out-of-range values are clamped and reported: “Go to page 99” shows page 40 and calls onPageChange(40).

Mixing modes

Control only what you need. Leave x undefined to let the viewer keep that state, and use defaultX to choose where it starts; the demo under Customization opens on page 5 at 125%, rotated.

Switching a prop between controlled and uncontrolled during the component’s life logs a development warning, as React inputs do.

The same pattern in your components

useControllableState is the hook the viewer uses. Build your own controls with the same contract.

import { useControllableState } from '@kingtech/react-pdf-viewer'; import { useState } from 'react'; interface CounterProps { value?: number; defaultValue?: number; onValueChange?: (value: number) => void; } /** A component with the same value / defaultValue / onValueChange contract as the viewer. */ function Counter({ value, defaultValue = 0, onValueChange }: CounterProps) { const [count, setCount] = useControllableState({ value, defaultValue, onChange: onValueChange, name: 'value', }); return ( <button type="button" className="demo-button" onClick={() => setCount((previous) => previous + 1)} > Clicked {count} times </button> ); } export default function Demo() { const [controlled, setControlled] = useState(10); return ( <div className="demo-controls"> <span>Uncontrolled:</span> <Counter defaultValue={0} /> <span>Controlled (capped at 12):</span> <Counter value={controlled} onValueChange={(next) => setControlled(Math.min(12, next))} /> </div> ); }

The setter is stable and accepts a value or an updater function; onChange fires only when the value actually changes.

Customization

Start an uncontrolled viewer exactly where you want it. The zoom reset button returns to defaultScale.

import { PdfViewer } from '@kingtech/react-pdf-viewer'; export default function Demo() { // Uncontrolled, but opening where you choose. `defaultScale` is also the reset-zoom target. return ( <PdfViewer source="/samples/multipage.pdf" defaultPage={5} defaultScale={1.25} defaultRotation={90} zoomReset /> ); }

For styling, see the customization guide.

Advanced / escape hatch

For one-off commands (“go to page 3”) without owning the state, use the imperative API.

Limitations

Values cannot be functions. useControllableState treats a function passed to the setter as an updater. Workaround: wrap function values in an object.
New documents reset uncontrolled state only. A new source opens on defaultPage; a controlled page is yours to reset. Workaround: reset your state when you change the source.

API

useControllableState — The value / defaultValue / onValueChange pattern as a hook: the one behind every controlled prop of the viewer.
UseControllableStateOptions — Options for useControllableState: the controlled value, the initial value while uncontrolled, and the change callback.
SetControllableState — Setter returned by useControllableState; accepts a value or an updater function.