# Loading states Show a loading view while a document downloads and an empty state when there is nothing to show, or replace both with your own. ## Basics While a document loads, the viewer shows a spinner and a status message, and keeps the toolbar in place. **Demo: The loading view** ```tsx import { PdfViewer } from '@kingtech/react-pdf-viewer'; // A request that never finishes, so the loading view stays visible. const neverResolves = () => new Promise(() => undefined); export default function Demo() { return ; } ``` The message is announced to assistive technology, and zoom and rotation already work so the first page renders the way the user left it. ### Empty state With no source (`null`, `undefined` or `''`) the viewer is idle: the toolbar shows `0 / 0` with navigation disabled and nothing loads. **Demo: No document yet** ```tsx import { PdfViewer } from '@kingtech/react-pdf-viewer'; export default function Demo() { // No source yet: the toolbar shows 0 / 0 with navigation disabled. return ; } ``` An empty source is idle from the very first render, so pages that pick a document later never flash a spinner. ## Document status `status` on the [imperative API](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/imperative-api/) and on [`usePdfDocument`](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/headless/) is one of `idle`, `loading`, `ready` or `error`. The root element also carries `data-status`, so you can style states in CSS: ```css .report-viewer[data-status='loading'] { opacity: 0.8; } ``` ## Customization `renderLoading` and `renderEmpty` replace the two views, for example with a skeleton that matches your page. **Demo: A skeleton loading view** ```tsx import { PdfViewer } from '@kingtech/react-pdf-viewer'; const neverResolves = () => new Promise(() => undefined); export default function Demo() { return ( (
)} /> ); } ``` Label text comes from `labels.loading` and `labels.empty`; see the [customization guide](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/customization/). ## Advanced / escape hatch `onDocumentLoad` fires once the document is ready, with its page count; see [Events](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/events/). ## Limitations - **No download progress.** The loading view does not show a percentage, because the viewer fetches the whole file before handing it to PDF.js. Workaround: download the file yourself with progress, then pass the bytes as the `source`. - **Page rendering has no separate indicator.** After the document loads, each page appears when it finishes rendering; the previous page stays visible until then, so there is no blank flash. ## API - [PdfDocumentStatus](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/api/pdf-document-status.md) - [PdfViewerProps](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/api/pdf-viewer-props.md) --- ## PdfDocumentStatus reference Lifecycle status of a document load: idle without a source, loading, ready with a document, or error with a `PdfViewerError`. ### Used by - [Loading states](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/loading-states.md) ### Import ```ts import type { PdfDocumentStatus } from '@kingtech/react-pdf-viewer'; ``` Signature: `type PdfDocumentStatus = 'idle' | 'loading' | 'ready' | 'error'` ### Properties | Name | Type | Default | Required | Description | | --- | --- | --- | --- | --- | | `idle` | `'idle'` | — | No | No source, or an HTTP error that `onHttpError` handled. | | `loading` | `'loading'` | — | No | Fetching or parsing the document. | | `ready` | `'ready'` | — | No | The document is loaded and pages can render. | | `error` | `'error'` | — | No | Loading failed; the error is available. | ### Source [packages/react-pdf-viewer/src/types.ts](https://github.com/kiralygyula92/react-pdf-viewer/blob/main/packages/react-pdf-viewer/src/types.ts#L57) --- ## PdfViewerProps reference Props for `PdfViewer`. Every piece of state supports the value / defaultValue / onChange trio. ### Used by - [Page navigation](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/page-navigation.md) - [Zoom](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/zoom.md) - [Rotation](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/rotation.md) - [Download](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/download.md) - [Print](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/print.md) - [Fit modes](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/fit-modes.md) - [Fullscreen](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/fullscreen.md) - [Continuous layout](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/continuous-layout.md) - [Thumbnails](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/thumbnails.md) - [Loading states](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/loading-states.md) - [Page number input](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/page-number-input.md) - [Links](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/links.md) - [Text layer](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/text-layer.md) - [Search](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/search.md) - [Password protection](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/password-protection.md) - [Rendering](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/rendering.md) ### Import ```ts import type { PdfViewerProps } from '@kingtech/react-pdf-viewer'; ``` ### Properties | Name | Type | Default | Required | Description | | --- | --- | --- | --- | --- | | `source` | `PdfSource \| null` | — | Yes | The document: a URL string or `URL`, or `ArrayBuffer` / `Uint8Array` / `Blob` / `File`. `null`, `undefined` and `''` show the empty state. | | `fileName` | `string` | `derived from the source` | No | Download file name. Default: a `File`’s name, the URL’s last `.pdf` segment, else `document.pdf`. | | `page` | `number` | — | No | Controlled 1-based page. Out-of-range values are clamped and reported through `onPageChange`. | | `defaultPage` | `number` | `1` | No | Initial page while uncontrolled, and the page every new document opens on. | | `onPageChange` | `(page: number) => void` | — | No | Called whenever the page changes, controlled or not. | | `scale` | `number` | — | No | Controlled scale: `1` = 100%, one PDF point per CSS pixel. | | `defaultScale` | `number` | `1` | No | Initial scale while uncontrolled; also the reset-zoom target and the scale at which fitting applies. | | `onScaleChange` | `(scale: number) => void` | — | No | Called whenever the scale changes. | | `rotation` | `Rotation` | — | No | Controlled clockwise rotation, added to each page’s intrinsic rotation. | | `defaultRotation` | `Rotation` | `0` | No | Initial rotation while uncontrolled. | | `onRotationChange` | `(rotation: Rotation) => void` | — | No | Called whenever the rotation changes. | | `fullscreen` | `boolean` | — | No | Controlled fullscreen state. Passing it selects `fullscreenMode="controlled"` unless a mode is set. | | `defaultFullscreen` | `boolean` | `false` | No | Initial fullscreen state while uncontrolled. | | `onFullscreenChange` | `(fullscreen: boolean) => void` | — | No | Called whenever fullscreen is entered or left. | | `fullscreenMode` | `FullscreenMode` | `'controlled' when fullscreen is passed, else 'native'` | No | `controlled`: layout only, the parent presents fullscreen (e.g. in its own dialog). `native`: the browser Fullscreen API on the viewer root, falling back to `overlay`. `overlay`: a fixed full-viewport layer with a focus trap; `Esc` closes it. | | `minScale` | `number` | `0.25` | No | Zoom floor (25%). | | `maxScale` | `number` | `5` | No | Zoom ceiling (500%). | | `scaleStep` | `number` | `0.05` | No | Increment of the zoom buttons and the `+` / `-` keys. | | `zoomLevels` | `readonly number[]` | — | No | Preset ladder, e.g. `[0.5, 1, 1.5, 2, 4]`: the zoom buttons step between presets instead of by `scaleStep`. | | `fitWidthAtDefaultScale` | `boolean` | `true` | No | At the default scale, shrink the page to the available width. | | `fitMode` | `'page' \| 'none' \| 'width'` | `'none'` | No | At the default scale, fill the width (`width`) or fit the whole page (`page`). Zooming away shows the page at true size. | | `password` | `string` | — | No | Password for encrypted documents. Changing it reloads the document. | | `pdfjsOptions` | `PdfJsDocumentOptions` | — | No | Per-instance `getDocument` overrides such as `cMapUrl`, `standardFontDataUrl` or `verbosity`. Source-related options are managed by the viewer. | | `toolbar` | `boolean \| ToolbarConfig` | `true` | No | `false` hides the toolbar; an object sets `position`, `actions` and `hiddenWhenCompact`. | | `compactBreakpoint` | `number` | `960` | No | Viewport width (px) below which the compact layout applies: less padding, and `hiddenWhenCompact` actions hidden outside fullscreen. | | `keyboardShortcuts` | `boolean` | `true` | No | Keyboard shortcuts while focus is inside the viewer. | | `printMode` | `'render' \| 'open-url'` | `'render'` | No | `render` prints through a hidden iframe, with progress and Cancel; `open-url` opens the PDF in a new tab. | | `maxCanvasPixels` | `number` | `16777216` | No | Canvas pixel budget per page (4096 × 4096). Above it, resolution degrades gracefully instead of failing. | | `labels` | `Partial` | `English (defaultLabels)` | No | Overrides for any visible string or accessible name. Keep the object stable (e.g. at module scope). | | `locale` | `string` | `the browser locale` | No | BCP 47 locale for number formatting, e.g. `hu-HU`. | | `layout` | `'single' \| 'continuous'` | `'single'` | No | One page at a time or vertical scrolling through all pages. Only the visible pages ±1 are rendered; the page indicator follows the scroll position. | | `textLayer` | `boolean` | `false` | No | Selectable, copyable text that assistive technology can read. | | `annotationLayer` | `boolean` | `false` | No | Clickable links: internal links navigate, external links open in a new tab with `rel="noopener noreferrer"`. | | `pageInput` | `boolean` | `false` | No | Editable page number in the toolbar. | | `zoomReset` | `boolean` | `false` | No | The zoom label becomes a button that resets zoom. | | `wheelZoom` | `boolean` | `false` | No | `Ctrl` / `⌘` + wheel and trackpad pinch zoom, anchored at the pointer. | | `passwordPrompt` | `boolean` | `false` | No | Ask for the password of encrypted documents instead of reporting `PASSWORD_REQUIRED`. | | `renderPasswordPrompt` | `(context: { incorrect: boolean; submit: (password: string) => void }) => ReactNode` | — | No | Replaces the built-in password form (with `passwordPrompt`). | | `thumbnails` | `boolean` | `false` | No | Lazily rendered page thumbnails sidebar, hidden in compact, non-fullscreen mode. | | `search` | `boolean` | `false` | No | Find bar with highlighting (implies `textLayer`). `Ctrl` / `⌘` + `F` focuses it, `Enter` / `Shift` + `Enter` step through matches, `Esc` clears. | | `renderLoading` | `() => ReactNode` | — | No | Replaces the loading view. | | `renderError` | `(error: PdfViewerError, actions: { retry: () => void }) => ReactNode` | — | No | Replaces the document and page error views. | | `renderToolbar` | `(api: PdfViewerApi) => ReactNode` | — | No | Replaces the toolbar. Render `<PdfToolbar api={api} />` inside to reuse parts. | | `renderEmpty` | `() => ReactNode` | — | No | Replaces the view shown without a source. | | `onDocumentLoad` | `(info: { numPages: number; fingerprint: string }) => void` | — | No | A document finished loading. | | `onPageRender` | `(info: PageRenderInfo) => void` | — | No | A page render completed. | | `onError` | `(error: PdfViewerError) => void` | — | No | Every failure except aborted loads, canceled renders and HTTP errors handled by `onHttpError`. | | `onDownload` | `(context: { fileName: string; data: Uint8Array }) => false \| void` | — | No | Before saving; `data` holds the already-loaded bytes. Return `false` to handle the download yourself. | | `onPrint` | `() => false \| void` | — | No | Before printing. Return `false` to handle printing yourself. | | `className` | `string` | — | No | Added to the root (`.rpv-root`). `rpv-theme-dark` and `rpv-theme-auto` select the dark presets. | | `style` | `CSSProperties` | — | No | Inline styles on the root, e.g. CSS variables. | | `id` | `string` | — | No | Id of the root element. | | `aria-label` | `string` | `labels.viewer` | No | Accessible name of the viewer region. | | `requestInit` | `RequestInit` | — | No | Extra `fetch` options for URL sources: headers, `credentials`, `mode`, … | | `fetcher` | `(url: string, init: RequestInit) => Promise` | — | No | Replaces `fetch` entirely, e.g. with an authenticated HTTP client. | | `onHttpError` | `(response: Response) => boolean \| void \| Promise` | — | No | Called for non-2xx responses. Return `true` when handled (e.g. after redirecting to sign-in): the viewer shows its empty state and does not call `onError`. | | `getHttpErrorMessage` | `(response: Response) => Promise` | — | No | Builds the `HTTP_ERROR` message. Return `undefined` for the default: an RFC 7807 `detail`, then `title`, then a JSON string body, then `Failed to fetch PDF: {status} {statusText}`. | ### Source [packages/react-pdf-viewer/src/types.ts](https://github.com/kiralygyula92/react-pdf-viewer/blob/main/packages/react-pdf-viewer/src/types.ts#L190)