PDFium Engine for React

The usePdfiumEngine hook is the bridge between the core PDF processing engine and your React application. Its primary purpose is to provide a managed engine instance for the main <EmbedPDF> component, which then orchestrates all the plugins and UI components.

Installation

The hook is included in the @embedpdf/engines package, which should be installed alongside @embedpdf/core.


npm install @embedpdf/core @embedpdf/engines


pnpm add @embedpdf/core @embedpdf/engines


yarn add @embedpdf/core @embedpdf/engines


bun add @embedpdf/core @embedpdf/engines

Primary Use Case: Powering the `<EmbedPDF>` Component

Most of the time, you will simply get the engine from the hook and pass it to the <EmbedPDF> provider. The provider and its plugins will handle the rest, including initialization.

This pattern allows you to build your entire viewer without ever calling engine.openDocument() or engine.renderPage() yourself.

MyViewer.tsx


import { usePdfiumEngine } from '@embedpdf/engines/react';
import { EmbedPDF } from '@embedpdf/core/react';
// ... import your desired plugins and components
 
function MyViewer() {
  const { engine, isLoading, error } = usePdfiumEngine();
 
  if (isLoading) {
    return <div>Loading PDF Engine...</div>;
  }
  if (error) {
    return <div>Error loading engine: {error.message}</div>;
  }
  
  // The engine is ready. Pass it to the provider.
  return (
    <EmbedPDF engine={engine} plugins={/* ... your plugins ... */}>
      {/* ... your viewer components like <Viewport />, <Toolbar />, etc. ... */}
    </EmbedPDF>
  );
}

Advanced Use Case: Direct Engine Interaction

For tasks that fall outside the plugin system—such as exporting a page image on a button click or performing a one-off text extraction—you can use the engine object directly.

💡

Note: When using the engine directly, you must ensure it has been initialized. The <EmbedPDF> component handles this for you, but if you’re using the engine standalone, you must call engine.initialize() yourself.


import { usePdfiumEngine } from '@embedpdf/engines/react'
import { ignore } from '@embedpdf/models'
import { useEffect, useState } from 'react'
 
export default function LoadingPDFiumExample() {
  const { isLoading, error, engine } = usePdfiumEngine()
  const [initialized, setInitialized] = useState(false)
 
  useEffect(() => {
    if (engine && !initialized) {
      if (engine.initialize) {
        const task = engine.initialize()
        task.wait(setInitialized, ignore)
      } else {
        setInitialized(true)
      }
    }
  }, [engine, initialized])
 
  if (error) {
    return (
      <div className="mt-3 rounded-md bg-red-50 p-4 text-sm font-medium text-red-800">
        Failed to initialize PDF engine: {error.message}
      </div>
    )
  }
 
  if (isLoading || !engine || !initialized) {
    return (
      <div className="mt-3 rounded-md bg-yellow-50 p-4 text-sm font-medium text-yellow-800">
        Loading PDF engine...
      </div>
    )
  }
 
  // Engine is ready to use
  return (
    <div className="mt-3 rounded-md bg-green-50 p-4 text-sm font-medium text-green-800">
      Engine loaded successfully!
    </div>
  )
}

Hook API Reference

The usePdfiumEngine hook accepts an optional configuration object and returns the engine’s state.

Return Values

engine: The PdfEngine instance, or null while loading.
isLoading: A boolean that is true while the engine’s WebAssembly is being downloaded and instantiated.
error: An Error object if loading or initialization fails, otherwise null.

For complete documentation of all available engine methods, see the @embedpdf/engines package documentation.

PDFium Engine for React

Installation

Primary Use Case: Powering the <EmbedPDF> Component

Advanced Use Case: Direct Engine Interaction

Hook API Reference

Return Values

Need Help?

Primary Use Case: Powering the `<EmbedPDF>` Component