Raster fallback

The exporter keeps simple document primitives vector, then falls back to raster for CSS effects that are expensive or risky to reproduce manually.

Automatic triggers

An element is rasterized when it uses one of these features:

The walker emits one raster primitive for the outermost matching region and skips its children, because the PNG already contains the subtree.

Manual trigger

Use data-pdf-raster="true" when you know a component is visually complex.

<div data-pdf-raster="true">
  <ThirdPartyChart />
</div>

This is useful for charts, maps, signatures, canvas-backed widgets, or any third-party component whose visual output matters more than selectable text.

How it works

The prepare phase scans the DOM before walking. Matching regions are captured with html-to-image at a pixel ratio of at least 2.

DOM region
  ↓ html-to-image
PNG data URL
  ↓ cached by element
RasterPrimitive
  ↓ embedded once by pdf-lib
PDF image XObject

Trade-offs

Raster fallback is intentionally selective:

• large raster regions increase PDF size
• text inside raster regions is not selectable
• CORS-restricted images or fonts inside the region may fail to inline
• very high device pixel ratios can create large PNGs

Use raster fallback for visual effects, not as the default export strategy.

When to force raster

Good candidates:

• brand-heavy cover sections
• charts with gradients or SVG layers
• transformed stamps or signatures
• cards where the shadow is part of the visual contract

Poor candidates:

• long paragraphs
• tables with hundreds of rows
• legal terms that should remain searchable/selectable