PDFx Documentation

The theme system is designed to be local and transparent.

1. Initialization: Running pdfx theme init creates a pdfx-theme.ts file in your local project.
2. Runtime: Components consume the theme at runtime using the usePdfxTheme() hook.
3. Implementation: The theme is a standard TypeScript object. There is no hidden context provider; the theme lives with your code, allowing for full control and visibility.

PDFx uses a registry-based model similar to shadcn/ui. Instead of installing a monolithic npm package, you use the pdfx CLI to fetch component source code directly from the documentation website's registry.

When you run pdfx add <name>, the CLI fetches a JSON manifest from the HTTPS registry, which contains the source code for the component. The CLI then writes these files directly into your project. This means you own the code once it is added, and there are no runtime dependencies on a @pdfx/components package.

PDFx components are compatible with Node.js environments. You can use @react-pdf/renderer methods like renderToFile, renderToBuffer, or renderToStream to generate and save PDFs on the server (e.g., in Express or Next.js API routes).

import { renderToFile } from '@react-pdf/renderer';
import { Document, Page } from '@react-pdf/renderer';
import { Heading } from './src/components/pdfx/heading/pdfx-heading';
import { Text } from './src/components/pdfx/text/pdfx-text';

const doc = (
  <Document>
    <Page size="A4" style={{ padding: 40 }}>
      <Heading level={1}>Monthly Report</Heading>
      <Text>Generated server-side with PDFx.</Text>
    </Page>
  </Document>
);

// Write straight to disk:
await renderToFile(doc, './output.pdf');

// …or get a Buffer to return from an API route / attach to an email:
// const buffer = await renderToBuffer(doc);

PDFx supports the Model Context Protocol (MCP), allowing AI IDEs or agents to access the PDFx registry for context about component structures. You can initialize this for specific clients like Cursor.

npx pdfx-cli@latest mcp init --client cursor

Because components are written directly into your project rather than being managed via package.json versions, you do not update them by bumping a package version. To update a component to the latest version from the registry, run the pdfx add command again using the --force flag.

pdfx add <name> --force

You can add specific, individual PDFx components directly into your local codebase. This allows you to fully own and customize the component code within your project. Use the add command followed by the component name.

npx pdfx-cli@latest add badge
npx pdfx-cli@latest add table form qrcode

To start using PDFx in your project, use the init command to set up the necessary configuration and project structure.

npx pdfx-cli@latest init

PDFx provides a CLI to scaffold pre-built PDF components into your React project. This approach allows you to own the component code completely with no runtime dependency on the PDFx package.

1. Initialize PDFx: Run npx pdfx-cli init to set up the necessary structure.
2. Add Components: Use npx pdfx-cli add <component-names> to copy specific components into your local ./components/pdfx directory. For example, to add heading, text, and badge, use:

   npx pdfx-cli add heading text badge

Instead of individual components, you can add full, pre-designed templates (blocks) like invoices or reports using the block add command.

npx pdfx-cli@latest block add invoice-modern
npx pdfx-cli@latest block add report-financial

In version 0.6.0, fixes were introduced for DataTable, Table, and PdfList components regarding layout and width handling.

• DataTable / Table: Fixed an issue where width props on TableCell or DataTable columns were ignored. The CLI now correctly respects width values in the following formats:
  • Numbers (e.g., 100 for pt)
  • Percentage strings (e.g., "25%")
  • Pixel strings (e.g., "50px")
• PdfList: Fixed an issue where rows would overlap when text wrapped to multiple lines across all variants (bullet, numbered, checklist, icon, and multi-level).

To apply these fixes to your existing installation, re-run the following commands:

pdfx add table
pdfx add data-table
pdfx add list

The PDFx registry provides a comprehensive set of components for building PDF documents. These components are exported from the main registry entrypoint and can be used to construct structured, styled layouts. Common component categories include:

• Typography: Heading, Text, Link, Badge, KeyValue.
• Layout: Stack, Section, Divider, PageBreak, KeepTogether.
• Data Display: Table, DataTable, PdfList, PdfCard, PdfGraph.
• Page Elements: PageHeader, PageFooter, PdfPageNumber, PdfWatermark.
• Interactive/Form Elements: PdfForm, PdfSignatureBlock, PdfQRCode.
• Media: PdfImage.

All components accept props defined by their respective [ComponentName]Props types and generally adhere to the PDFComponentProps base type.