EasyPdf Documentation

@easypdf/react is a powerful and free React library that simplifies PDF generation from React components. It provides a flexible and intuitive API for creating beautiful PDFs with features like custom styling, watermarks, headers, footers, and more.

Installation

npm install @easypdf/react
# or
yarn add @easypdf/react

Setup

First, wrap your app with the EasyPdf provider:

import { useRoutes } from "react-router-dom";
import { EasyPdfProvider, EasyPdf } from "@easypdf/react";

// Initialize EasyPdf
const easyPdf = EasyPdf.initialize();

export default function App() {
  const element = useRoutes(routes);

  return <EasyPdfProvider instance={easyPdf}>{element}</EasyPdfProvider>;
}

Configuration

Configurations can be provided at different levels and will be merged in the following order:

1. Default configuration
2. Configuration passed to useEasyPdf hook
3. Configuration passed to individual methods

// Configuration at hook level
const { pdfRef, downloadPDF } = useEasyPdf({
  pageSize: "A4",
  watermark: {
    text: "DRAFT",
  },
  container: {
    style: {
      width: "800px", // Fixed width for PDF content
      margin: "0 auto",
    },
  },
});

// Configuration at method level - merges with hook config
await downloadPDF(pdfRef, {
  watermark: {
    opacity: 0.3, // Merges with the watermark config from hook
  },
  filename: "document.pdf",
});

Styling

EasyPdf supports all CSS styling methods, and they work the same way in both visual and programmatic modes:

Inline Styles

<div ref={pdfRef}>
  <h1
    style={{
      color: "#333",
      fontSize: "24px",
      fontFamily: "Arial, sans-serif",
      marginBottom: "1em",
      textAlign: "center",
    }}
  >
    Styled Title
  </h1>
</div>

CSS Classes

<div ref={pdfRef}>
  <style>
    {`
      .pdf-title {
        color: #2c3e50;
        font-size: 2em;
        border-bottom: 2px solid #3498db;
        padding-bottom: 0.5em;
      }

      .pdf-section {
        background-color: #f8f9fa;
        border-radius: 8px;
        padding: 1em;
        margin: 1em 0;
        box-shadow: 0 2px 4px rgba(0,0,0,0.1);
      }
    `}
  </style>

  <h1 className="pdf-title">Styled with CSS Classes</h1>
  <div className="pdf-section">
    <p>Section with background and shadow.</p>
  </div>
</div>

Container Styles

The container.style configuration option allows you to control the PDF content width and layout. This is useful when you want to maintain consistent sizing regardless of the PDF page size:

const { pdfRef } = useEasyPdf({
  container: {
    style: {
      width: "800px", // Fixed width for PDF content
      margin: "0 auto",
      padding: "20px",
      backgroundColor: "#ffffff",
    },
  },
});

If not specified, content will adapt to the PDF page size by default.

Core Features

Performance

EasyPdf uses smart chunking and non-blocking rendering to maintain UI responsiveness:

• Non-Blocking Generation: Generate PDFs without freezing the browser
• Smart Page Breaking: Intelligent handling of unbreakable elements and text flow
• Memory Efficient: Automatic cleanup of resources and optimized rendering

Learn more about performance optimizations

Page Breaking

EasyPdf includes a sophisticated page breaking algorithm that handles content flow across pages intelligently:

• Non-breakable Elements: Tables, figures, images, pre-formatted text, code blocks, lists, and elements with no-break class
• Smart Text Breaking: Prefers sentence breaks, then row breaks, and finally block breaks
• Manual Control: Support for forced page breaks using CSS

Headers and Footers

Add consistent headers and footers across all pages with customizable text, styling, and positioning.

Watermarks

Apply customizable watermarks with control over text, size, opacity, angle, and color.

Error Handling

The hook provides built-in error handling that works consistently across both modes:

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

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

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

      <div ref={pdfRef}>{/* Content here */}</div>
    </div>
  );
}

Usage Modes

EasyPdf offers two modes of operation that share all the above features and configurations:

1. Visual Mode - Design PDFs using React components with real-time preview
2. Programmatic Mode - Generate PDFs dynamically with programmatic content creation

Choose the mode that best fits your use case - all features, styling options, and configurations work identically in both modes.

Next Steps

• Configuration Guide - Learn about all configuration options
• Visual Mode Guide - Learn how to use visual mode
• Hook API Reference - Explore the hook API
• Examples - See more examples