HTML to PDF Compatibility

NativeElixirPdfUtilities.HtmlToPdf is a native document renderer for predictable server-side PDFs such as reports, invoices, labels, statements, and simple generated documents. It is not a browser engine and does not claim full browser compatibility.

For runnable templates, styling patterns, and caller-side error handling examples, see HTML to PDF Examples.

Unsupported or malformed input is rejected instead of being silently approximated. Rendering failures return a broad reason with diagnostic detail, for example:

{:error,
 {:invalid_css,
  %{
    stage: :css,
    reason: :invalid_css,
    message: ~s(line 18: selector "li >" is invalid or unsupported),
    line: 18,
    column: 1,
    source: "li >"
  }}}

The detail map always includes :stage, :reason, and :message. It includes :line, :column, and :source when the renderer can locate the source snippet. CSS is strict: unknown declarations and unsupported values fail with :invalid_css rather than being ignored.

HtmlToPdf Options

Running Headers, Footers, and Page Numbers

Running page furniture is an opt-in rendering option:

HtmlToPdf.render(html,
  margin: "18mm",
  page_furniture: [
    header: [
      default: "<div>Account statement</div>",
      first: false,
      odd: "<div>Account statement</div>",
      even: "<div style=\"text-align: right\">Account statement</div>"
    ],
    footer: "<div style=\"text-align: right\">Page {{page}} of {{pages}}</div>"
  ]
)

Templates use the same supported HTML, CSS, configured stylesheets, local images, and font registry as normal rendering. A plain text fragment is also accepted. Main-document embedded <style> rules are not automatically copied into a separate furniture template, so shared rules should be supplied through :stylesheets or included in the furniture HTML.

Variant selection is deterministic:

1. :first is selected for page one when present.
2. Otherwise, a matching :odd or :even variant is selected when present.
3. Otherwise, :default is selected.

A false or nil variant renders nothing. First-page-only furniture uses [default: false, first: template]; except-first-page furniture uses [default: template, first: false].

{{page}} expands to the current one-based page number and {{pages}} expands to the final total page count. Substitution happens before each furniture template is laid out.

Furniture is placed inside the existing page margins and does not change body pagination. Headers must fit the top margin and footers must fit the bottom margin. If a template does not fit, rendering returns an :invalid_layout diagnostic describing the furniture position, measured height, and available margin. Reserve enough @page or :margin space for the header and footer.

HTML Support Matrix

CSS Support Matrix

Layout Details

Block, list, table, flexbox, and grid layout are deterministic and intentionally narrower than browser layout. Tables use deterministic column sizing based on declared widths, available table width, and intrinsic unbreakable content, with support for collapsed borders, cell backgrounds, colspan, repeated multi-row headers, and missing trailing cells in shorter rows. Flexbox and grid support document-oriented text, images, and nested block-card items, not the full browser algorithms.

Pagination supports automatic page breaks, manual page breaks, page margins, line-level paragraph fragmentation, best-effort keep-together behavior for break-inside: avoid, and repeated table headers when table bodies continue across pages. An avoided paragraph that is taller than the printable page is fragmented so that all text remains visible.

Images support 8-bit, non-interlaced RGB and RGBA PNGs, JPEGs, and SVG data URIs, plus the same PNG subset and JPEGs from absolute local paths and base_url-relative paths. SVG data URIs are rasterized to PNG with the lightweight resvg NIF using local in-process rendering; remote URLs and unsafe relative paths are rejected. Greyscale, indexed-color, 16-bit, and Adam7-interlaced PNG decoding is scheduled for 0.21.0.

Fonts support built-in PDF fonts (Helvetica, Courier, Times-Roman and their bold/italic variants), explicit font options, local CSS @font-face declarations, and bundled DejaVu Sans regular, bold, oblique, and bold-oblique fallback faces. Relative @font-face URLs resolve against the containing stylesheet directory or :base_url; HTTP(S), data URLs, local(...)-only sources, WOFF, WOFF2, and CFF-flavored OpenType fonts are rejected. Convert unsupported web fonts to TTF before rendering.

Font fallback is resolved once before layout so wrapping and pagination use the final glyph metrics. For each Unicode grapheme, the renderer tries the selected CSS face, the remaining requested family list, configured font faces in declaration order, and then the closest bundled DejaVu Sans weight/style. Adjacent graphemes using the same face remain one text run. Invalid UTF-8 returns :invalid_encoding; a grapheme absent from every candidate returns :unsupported_glyph with the grapheme and codepoints in the diagnostic instead of writing corrupt PDF text.

Embedded fonts use TrueType glyph widths, Type0/CID PDF resources, and basic Unicode mapping. Glyph availability does not imply complex shaping: Arabic, Indic scripts, Thai, emoji sequences, bidirectional layout, and other advanced typography remain unsupported.

Unsupported Features

These features are intentionally outside the current renderer boundary:

• JavaScript and runtime DOM behavior.
• script, canvas, video, audio, iframe, and interactive form behavior.
• Remote asset fetching.
• CSS floats, absolute/fixed positioning, transforms, animations, media queries beyond the documented print subset, pseudo-elements beyond ::before/::after, and pseudo-classes beyond the documented selector subset. Repeated page furniture uses the explicit :page_furniture option; position: fixed remains deferred because the flow layout model does not yet support positioned offsets or removing positioned elements from flow.
• Nested counters(...), counter styles, list-marker counter integration, and CSS counter(page)/counter(pages). Repeated page numbering uses the explicit page-furniture {{page}} and {{pages}} tokens.
• Full browser-compatible table, flexbox, and grid algorithms.
• Complex text shaping and bidirectional layout.

Validation Expectations

Automated tests cover parsing, CSS cascade, layout dimensions, pagination, PDF object output, images, fonts, links, and end-to-end rendering. Human visual validation is still required before accepting broad layout changes because PDF layout regressions can be visually obvious while remaining structurally valid.

Browser parity tests are available as an explicit, slower conformance suite. They render small HTML fixtures with Chromium, render the same fixtures with the native renderer, rasterize both PDFs with pdftoppm, and compare page pixels with a tolerance for font antialiasing.

For the current fixture-by-feature coverage audit, see HTML to PDF Browser Parity Coverage.

The parity suite is excluded from normal mix test runs because it requires local browser tooling. Run it when changing CSS, layout, table, flexbox, grid, border, page sizing, font, image, or pagination behavior:

CHROMIUM_BIN=/usr/bin/chromium mise exec -- mix test.browser_parity

Set PDFTOPPM_BIN if pdftoppm is not on PATH.

New HTML-to-PDF features must include focused unit coverage in the relevant parser, style, layout, pagination, or PDF writer tests. If the feature changes visible rendering, add or update a browser parity fixture and keep the parity suite green before documenting the feature as supported.

Current parity fixtures cover:

Real production environment fixtures are also included:

The artifact directory for a failing fixture is reported in the assertion message under tmp/browser_parity/<fixture-name>/ and contains Chromium/native PDFs plus rasterized PPM pages for inspection.