useEasyPdf Hook API Reference

The useEasyPdf hook is the main interface for generating PDFs in both visual and programmatic modes.

Basic Usage

import { useEasyPdf } from "@easypdf/react";

function PDFGenerator() {
  const { pdfRef, downloadPDF } = useEasyPdf();

  return (
    <div>
      <button onClick={() => downloadPDF(pdfRef)}>Download PDF</button>
      <div ref={pdfRef}>
        <h1>Hello, PDF!</h1>
      </div>
    </div>
  );
}

Hook Signature

const useEasyPdf = (initialConfig?: PDFConfig) => { ... }

The optional initialConfig sets defaults for all PDF operations from this hook instance.

Return Values

Name	Type	Description
pdfRef	React.RefObject<HTMLDivElement>	Attach to the element you want to capture as PDF
downloadPDF	(source: RefObject<HTMLDivElement> | Blob | string | null, config?: PDFConfig) => Promise<void>	Generate and download a PDF
createPDF	(content: React.ReactNode, config?: PDFConfig) => Promise<void>	Render JSX to PDF and download (programmatic)
createPDFBlob	(content: React.ReactNode, config?: PDFConfig) => Promise<Blob>	Render JSX to a PDF Blob (programmatic)
viewPDF	(content: React.ReactNode | Blob, config?: PDFConfig) => Promise<void>	Open PDF in a new browser tab
isLoading	boolean	true while any PDF operation is in progress
error	Error | null	Set if the last operation threw an error

Methods

downloadPDF

Generates a PDF and triggers a browser download. Works in two ways depending on what you pass as the first argument:

// From a ref (Visual Mode) — captures the element's current DOM
await downloadPDF(pdfRef, { filename: "document.pdf" });

// From a Blob — downloads a blob you already have
const blob = await createPDFBlob(content);
await downloadPDF(blob, { filename: "document.pdf" });

// Shorthand: pass a filename string to use pdfRef with that filename
await downloadPDF("document.pdf");

Parameters

Name	Type	Description
source	RefObject<HTMLDivElement> | Blob | string | null	Ref to capture, a Blob to download, or a filename string (uses pdfRef)
config	PDFConfig	Optional config, merged with hook and global config

---

createPDF

Renders a JSX element off-screen and downloads the result as a PDF. Use this when you don't want to display the content on screen first.

await createPDF(
  <div>
    <h1>Generated PDF</h1>
    <p>Content rendered off-screen.</p>
  </div>,
  { filename: "generated.pdf" }
);

Parameters

Name	Type	Description
content	React.ReactNode	JSX content to render and download
config	PDFConfig	Optional config

---

createPDFBlob

Renders a JSX element off-screen and returns the PDF as a Blob. Useful when you need to upload it, display a preview, or handle the file yourself.

const blob = await createPDFBlob(
  <div>
    <h1>Hello, PDF!</h1>
  </div>,
  { filename: "document.pdf" }
);

Parameters

Name	Type	Description
content	React.ReactNode	JSX content to convert
config	PDFConfig	Optional config

Returns

Promise<Blob> — a PDF blob you can download, upload, or open.

---

viewPDF

Opens a PDF in a new browser tab. Accepts either JSX content (rendered off-screen) or an existing Blob.

// From JSX
await viewPDF(<div><h1>Preview</h1></div>);

// From an existing blob
const blob = await createPDFBlob(content);
await viewPDF(blob);

---

Loading State

All operations share a single isLoading flag:

function PDFGenerator() {
  const { pdfRef, downloadPDF, isLoading } = useEasyPdf();

  return (
    <div>
      <button onClick={() => downloadPDF(pdfRef)} disabled={isLoading}>
        {isLoading ? "Generating..." : "Download PDF"}
      </button>
      <div ref={pdfRef}>
        <h1>Hello, PDF!</h1>
      </div>
    </div>
  );
}

Error Handling

function PDFGenerator() {
  const { pdfRef, downloadPDF, isLoading, error } = useEasyPdf();

  return (
    <div>
      {error && <div className="error">Error: {error.message}</div>}

      <button onClick={() => downloadPDF(pdfRef)} disabled={isLoading}>
        {isLoading ? "Generating..." : "Download PDF"}
      </button>

      <div ref={pdfRef}>
        <h1>Hello, PDF!</h1>
      </div>
    </div>
  );
}

Configuration Priority

Config is merged in this order (later wins):

1. Default config (pageSize: "A4", margins: 20px, scale: 2, white background)
2. initialConfig passed to useEasyPdf(initialConfig)
3. Per-call config passed to downloadPDF, createPDF, etc.

const { pdfRef, downloadPDF } = useEasyPdf({
  pageSize: "A4",         // hook-level default
  watermark: { text: "DRAFT" },
});

await downloadPDF(pdfRef, {
  filename: "final.pdf",  // call-level override
  watermark: { opacity: 0.3 }, // merges into existing watermark config
});

Examples

Visual Mode

function VisualPDFGenerator() {
  const { pdfRef, downloadPDF, isLoading } = useEasyPdf({
    pageSize: "A4",
    margins: { top: 20, right: 20, bottom: 20, left: 20 },
  });

  return (
    <div>
      <button onClick={() => downloadPDF(pdfRef)} disabled={isLoading}>
        {isLoading ? "Generating..." : "Download PDF"}
      </button>

      <div ref={pdfRef}>
        <h1>Document Title</h1>
        <p>Document content...</p>
      </div>
    </div>
  );
}

Programmatic Mode

function ProgrammaticPDFGenerator() {
  const { createPDF, isLoading } = useEasyPdf();

  const generatePDF = async () => {
    await createPDF(
      <div>
        <h1>Generated PDF</h1>
        <p>Generated content...</p>
      </div>,
      { filename: "generated.pdf" }
    );
  };

  return (
    <button onClick={generatePDF} disabled={isLoading}>
      {isLoading ? "Generating..." : "Generate PDF"}
    </button>
  );
}

With Custom Styling

function StyledPDFGenerator() {
  const { pdfRef, downloadPDF } = useEasyPdf({
    styles: {
      backgroundColor: "#ffffff",
      defaultFontSize: 12,
      defaultFontFamily: "Arial, sans-serif",
      defaultTextColor: "#333333",
      customCSS: `
        .pdf-title { font-size: 24px; color: #2c3e50; text-align: center; }
        .pdf-section { margin: 15px 0; padding: 20px; background: #f8f9fa; }
      `,
    },
  });

  return (
    <div>
      <button onClick={() => downloadPDF(pdfRef)}>Download PDF</button>

      <div ref={pdfRef}>
        <h1 className="pdf-title">Styled Document</h1>
        <div className="pdf-section">
          <p>Content with custom styling...</p>
        </div>
      </div>
    </div>
  );
}

Related

• Configuration Guide
• Visual Mode
• Programmatic Mode