Fullscreen

Show the document fullscreen with the browser's Fullscreen API, an in-page overlay, or inside your own dialog.

Basics

The fullscreen button puts the viewer into browser fullscreen; Esc or the button leaves it.

import { PdfViewer } from '@kingtech/react-pdf-viewer'; export default function Demo() { // The fullscreen button uses the browser Fullscreen API; Esc leaves it. return <PdfViewer source="/samples/letter-3pages.pdf" />; }

The button’s label and icon follow the state, and the document is never reloaded when fullscreen changes. f toggles fullscreen from the keyboard.

Overlay

fullscreenMode="overlay" covers the browser window with a fixed layer instead. Focus stays inside the viewer, the page behind stops scrolling, and Esc closes it.

import { PdfViewer } from '@kingtech/react-pdf-viewer'; export default function Demo() { // A full-viewport layer inside the page: focus is trapped, the page behind stops scrolling. return <PdfViewer source="/samples/letter-3pages.pdf" fullscreenMode="overlay" />; }

Where element fullscreen is unavailable, native mode falls back to the overlay automatically.

Controlled by your app

Passing fullscreen selects fullscreenMode="controlled": the viewer switches to its fullscreen layout and your component decides how to present it, for example in your own dialog.

import { PdfViewer } from '@kingtech/react-pdf-viewer'; import { useState } from 'react'; export default function Demo() { const [fullscreen, setFullscreen] = useState(false); const viewer = ( <PdfViewer source="/samples/letter-3pages.pdf" fullscreen={fullscreen} onFullscreenChange={setFullscreen} /> ); // `fullscreen` is passed, so the mode is "controlled": the viewer switches to its fullscreen // layout and this component decides how to present it. The viewer stays mounted. return fullscreen ? ( <div role="dialog" aria-modal="true" aria-label="Document" style={{ position: 'fixed', inset: 0, zIndex: 1000, background: '#fff', overflowY: 'auto' }} > {viewer} </div> ) : ( viewer ); }

Mode	Who presents fullscreen	Use when
`native` (default without `fullscreen`)	The browser	You want real fullscreen
`overlay`	The viewer, as an in-page layer	Embedded pages, or iframes without fullscreen permission
`controlled` (default with `fullscreen`)	Your app	Your design system already has a full-screen dialog

Customization

The fullscreen background, padding and stacking order are CSS variables, and both button labels can be renamed.

import { PdfViewer } from '@kingtech/react-pdf-viewer'; import type { CSSProperties } from 'react'; const style = { '--rpv-fullscreen-bg': '#0f172a', '--rpv-toolbar-bg': '#334155', '--rpv-viewport-padding-fullscreen': '48px', } as CSSProperties; export default function Demo() { return ( <PdfViewer source="/samples/letter-3pages.pdf" fullscreenMode="overlay" labels={{ enterFullscreen: 'Focus mode', exitFullscreen: 'Leave focus mode' }} style={style} /> ); }

See --rpv-fullscreen-bg, --rpv-viewport-padding-fullscreen and --rpv-overlay-z-index in the CSS variables reference and the customization guide.

Advanced / escape hatch

toggleFullscreen() and the fullscreen value on the imperative API work in every mode. onFullscreenChange reports changes made by the browser too, such as pressing Esc in native fullscreen.

Limitations

Native fullscreen needs permission inside iframes. A cross-origin iframe must allow it (allow="fullscreen"); otherwise the viewer falls back to the overlay, which covers only the iframe. Workaround: add the allow attribute, or open the document in a top-level page.
The overlay is confined by transformed ancestors. A CSS transform, filter or contain on an ancestor makes the fixed layer cover that ancestor instead of the window. Workaround: use controlled mode and render your dialog outside the transformed element.
Some mobile browsers do not support element fullscreen. The viewer falls back to the overlay where the Fullscreen API is unavailable; this fallback has not been verified on every mobile browser.

API

FullscreenMode — How fullscreen is presented: the browser Fullscreen API, a full-viewport overlay, or layout only while the parent presents it.
PdfViewerProps — Props for PdfViewer. Every piece of state supports the value / defaultValue / onChange trio.