Authenticated requests

Load protected PDFs with cookies, headers or your own HTTP client, and handle expired sessions and HTTP errors your way.

URL sources are fetched by the viewer with fetch and handed to PDF.js as bytes. That lets you shape the request, and lets the viewer see HTTP statuses.

Basics

requestInit adds fetch options such as credentials and headers to the request.

import { PdfViewer } from '@kingtech/react-pdf-viewer'; export default function Demo() { // Extra fetch options for URL sources: send cookies and a custom header. return ( <PdfViewer source="/samples/letter-3pages.pdf" requestInit={{ credentials: 'include', headers: { 'X-Requested-With': 'react-pdf-viewer' } }} /> ); }

Your own HTTP client

fetcher(url, init) replaces fetch entirely, for example with a client that adds and refreshes tokens. init.signal is aborted when the source changes.

import { PdfViewer } from '@kingtech/react-pdf-viewer'; import { useCallback, useState } from 'react'; const TOKEN = 'demo-token'; /** Stand-in for your API: rejects requests without a bearer token. */ async function api(url: string, init: RequestInit): Promise<Response> { if (new Headers(init.headers).get('Authorization') !== `Bearer ${TOKEN}`) { return new Response(JSON.stringify({ title: 'Unauthorized', status: 401 }), { status: 401, headers: { 'Content-Type': 'application/problem+json' }, }); } return fetch(url, { signal: init.signal ?? null }); } export default function Demo() { const [signedIn, setSignedIn] = useState(false); const [notice, setNotice] = useState(''); const fetcher = useCallback( (url: string, init: RequestInit) => api(url, { ...init, headers: signedIn ? { Authorization: `Bearer ${TOKEN}` } : {} }), [signedIn], ); return ( <> <p className="demo-controls"> <label> <input type="checkbox" checked={signedIn} onChange={(event) => { setSignedIn(event.target.checked); setNotice(''); }} /> Signed in </label> {notice && <span role="status">{notice}</span>} </p> <PdfViewer // The fetcher applies to the next load: remount to load again with the new token. key={String(signedIn)} source="/samples/letter-3pages.pdf" fetcher={fetcher} onHttpError={(response) => { if (response.status === 401) { setNotice('401 Unauthorized: sign in to load the document.'); return true; // handled: empty state, no error view, no onError } return false; }} /> </> ); }

Handling HTTP errors

onHttpError(response) runs for every non-2xx response. Return true when you have handled it (for example by redirecting to sign-in): the viewer shows its empty state and does not call onError. Otherwise the error view appears with the message from getHttpErrorMessage.

<PdfViewer
  source={url}
  requestInit={{ credentials: 'include' }}
  onHttpError={(response) => {
    if (response.status === 401) {
      signIn({ returnTo: window.location.href });
      return true;
    }
  }}
/>

By default the message is read from an RFC 9457 (formerly 7807) problem body (detail, then title), then a JSON string body, then Failed to fetch PDF: {status} {statusText}.

Cross-origin documents

Reading a PDF from another origin requires the server to send Access-Control-Allow-Origin for your origin; sending cookies additionally requires credentials: 'include' and Access-Control-Allow-Credentials: true. A blocked request surfaces as a NETWORK_ERROR, because browsers do not tell scripts why a request was blocked. When you cannot change the server, proxy the file through your own origin.

Customization

getHttpErrorMessage(response) writes the error message for your API’s statuses. Return undefined to keep the default.

import { PdfViewer } from '@kingtech/react-pdf-viewer'; export default function Demo() { return ( <PdfViewer source="/samples/archived-report.pdf" getHttpErrorMessage={ async (response) => response.status === 404 ? 'This report has been archived. Ask your administrator to restore it.' : undefined // use the default message for other statuses } /> ); }

To replace the whole error view, see Error states and the customization guide.

Advanced / escape hatch

If requests need logic the viewer cannot express (multi-step downloads, signed URLs fetched from another endpoint), fetch the bytes yourself and pass them as a Blob or ArrayBuffer source. usePdfDocument accepts the same request options.

Limitations

Request options apply to the next load. Changing requestInit or fetcher does not reload the current document. Workaround: change the viewer’s key, or call reload() on the imperative API.
No range requests. The whole file is downloaded before rendering starts. Workaround: none within the viewer; keep very large documents split server-side.
Error handlers share one response. onHttpError and getHttpErrorMessage receive the same Response, and the default message reads a clone of its body. Workaround: read bodies with response.clone().json() in your handlers so the default message still works.

API

PdfRequestOptions — Controls how string and URL sources are fetched: extra fetch options, a replacement fetcher and the handling of HTTP errors.