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.

import { PdfViewer } from '@kingtech/react-pdf-viewer'; // A request that never finishes, so the loading view stays visible. const neverResolves = () => new Promise<Response>(() => undefined); export default function Demo() { return <PdfViewer source="/samples/letter-3pages.pdf" fetcher={neverResolves} />; }

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.

import { PdfViewer } from '@kingtech/react-pdf-viewer'; export default function Demo() { // No source yet: the toolbar shows 0 / 0 with navigation disabled. return <PdfViewer source={null} />; }

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 and on usePdfDocument is one of idle, loading, ready or error. The root element also carries data-status, so you can style states in 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.

import { PdfViewer } from '@kingtech/react-pdf-viewer'; const neverResolves = () => new Promise<Response>(() => undefined); export default function Demo() { return ( <PdfViewer source="/samples/letter-3pages.pdf" fetcher={neverResolves} renderLoading={() => ( <div role="status" style={{ padding: 32, textAlign: 'center' }}> <div aria-hidden="true" style={{ width: 240, height: 310, margin: '0 auto 12px', background: '#e2e8f0', borderRadius: 8, }} /> Preparing your document… </div> )} /> ); }

Label text comes from labels.loading and labels.empty; see the customization guide.

Advanced / escape hatch

onDocumentLoad fires once the document is ready, with its page count; see 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 — Lifecycle status of a document load: idle without a source, loading, ready with a document, or error with a PdfViewerError.
PdfViewerProps — Props for PdfViewer. Every piece of state supports the value / defaultValue / onChange trio.