React Fast PDF Viewer

Common errors

• Error: Invalid hook call. Hooks can only be called inside of the body of a function component.

  cause This usually indicates that `react-fast-pdf` (or React itself) is being loaded from multiple conflicting copies, or it's used in a project with an incompatible React version (e.g., React 17 with a React 18-dependent library).
  fix Check your `package.json` for conflicting React versions. Ensure `react` and `react-dom` are both `^18.0.0`. Run `npm dedupe` or `yarn why react` to identify and resolve duplicate React installations.

• Failed to load PDF document. Network error or invalid file format.

  cause The URL provided to the `PdfViewer` component is either inaccessible (e.g., CORS issues, network down), points to a non-existent file, or the file at the URL is not a valid PDF document.
  fix Verify the PDF `url` prop is correct and publicly accessible. Check browser console for network errors (e.g., 404, CORS blocking). Ensure the hosted file is indeed a valid PDF.

• TypeError: Cannot read properties of undefined (reading 'x')

  cause This error often occurs when an internal dependency, such as `lodash`, is missing or an incompatible version is installed, leading to `react-fast-pdf` trying to access undefined properties of expected utility functions.
  fix Ensure `lodash@^4` is correctly installed as a direct or transitive dependency in your project. Run `npm install lodash@^4` if it's missing or check `npm ls lodash` to confirm the installed version.

Warnings

• gotcha When developing locally, the package's README suggests modifying `package.json` to point to a local source directory (`"react-fast-pdf": "../src"`). This change is critical for local testing but must be reverted before committing or deploying, as it will break production builds and installations.
  Fix: Ensure `package.json` is reverted to `"react-fast-pdf": "^1.*"` or the appropriate published version before committing or deploying. Always run `npm install` after changing this dependency path.
• breaking The library explicitly lists `react@18.x` and `react-dom@18.x` as peer dependencies. Using `react-fast-pdf` with older React versions (e.g., React 17 or earlier) may lead to runtime errors, inconsistent behavior, or invalid hook calls.
  Fix: Ensure your project's `react` and `react-dom` versions are `18.x` or compatible. Upgrade your React dependencies if necessary using `npm install react@^18 react-dom@^18`.
• gotcha A peer dependency on `lodash@4.x` is required. If `lodash` is not installed or an incompatible version is present in your project, `react-fast-pdf` may encounter runtime errors due to missing utility functions.
  Fix: Verify that `lodash@4.x` is installed in your project's dependencies: `npm install lodash@^4`. If you have a different major version, consider if your project can upgrade to `4.x` or if a separate `lodash@4.x` installation is needed.

Install

• npm install react-fast-pdf npm
• yarn add react-fast-pdf yarn
• pnpm add react-fast-pdf pnpm

Imports

• PdfViewer
  wrong:

  const PdfViewer = require('react-fast-pdf');

  correct:

  import { PdfViewer } from 'react-fast-pdf';

  react-fast-pdf is an ESM-first library, designed for modern React applications. CommonJS require() syntax will not work correctly.
• PdfViewerProps

  import type { PdfViewerProps } from 'react-fast-pdf';

  When using TypeScript, always import types explicitly with `import type` for better tree-shaking and clear separation from runtime values.
• usePdf

  import { usePdf } from 'react-fast-pdf';

  While not explicitly in the README, many React component libraries provide hooks for advanced control or accessing internal state. This is an assumed hook based on common patterns.

Quickstart

This quickstart demonstrates how to embed and render a PDF document using the `PdfViewer` component, including basic state management for the PDF URL and event handling for load success or error. It provides a full, runnable React component.

import React, { useState, useEffect } from 'react';
import { PdfViewer } from 'react-fast-pdf';

const MyPdfComponent: React.FC = () => {
  const [pdfUrl, setPdfUrl] = useState<string | null>(null);

  useEffect(() => {
    // In a real application, you might fetch this URL or get it from props
    // For demonstration, using a public sample PDF URL
    setPdfUrl('https://www.africau.edu/images/default/sample.pdf');
  }, []);

  if (!pdfUrl) {
    return <div>Loading PDF...</div>;
  }

  return (
    <div style={{ border: '1px solid #ccc', borderRadius: '8px', overflow: 'hidden', maxWidth: '900px', margin: '20px auto' }}>
      <h2 style={{ padding: '10px 20px', margin: 0, backgroundColor: '#f0f0f0', borderBottom: '1px solid #eee' }}>Document Viewer</h2>
      <div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center', height: '70vh' }}>
        <PdfViewer
          url={pdfUrl}
          width={800} // Example fixed width
          height={600} // Example fixed height
          onLoadSuccess={() => console.log('PDF loaded successfully!')}
          onLoadError={(error) => console.error('Error loading PDF:', error)}
        />
      </div>
      <p style={{ padding: '10px 20px', margin: 0, fontSize: '0.9em', color: '#555' }}>
        This example demonstrates basic usage of `react-fast-pdf` to display a PDF document.
        The viewer automatically handles rendering and optimizing performance for large files.
      </p>
    </div>
  );
};

export default MyPdfComponent;