HTML and CSS support

Use the renderer for reports, invoices, statements, forms, and labels. Start with a working example, then choose the features you need below. Unsupported HTML tags and CSS properties return an error. Some accepted @page declarations have no rendering effect; see page declarations without an effect.

HTML support

Quote attribute values and close non-void tags. Put inline elements and form controls inside a block such as div or p. They cannot sit directly under body or at the document root. Supported controls create editable AcroForm fields by default. Use forms: :static for static artwork. See field naming and filling. Links support http://, https://, and mailto: destinations.

Use id, class, and style to apply CSS. Supported elements also accept relevant image, link, table-span, and form-value attributes.

CSS support

Body lengths support pt, px, mm, cm, in, rem, supported percentages, and unitless 0. Leading decimals such as .5mm are accepted. Letter spacing also accepts em. Flex and grid support gaps, alignment, ordering, and track/item sizing, but not every browser layout rule.

white-space: nowrap collapses whitespace and prevents automatic wrapping. Explicit <br> breaks still apply; long lines can overflow their container.

Render options

Pass options to HtmlToPdf.render(html, options) or render_file/3.

Page size and margins

Prefer size strings with explicit units for custom dimensions.

Page-size and margin strings accept pt, px, mm, cm, in, q, and pc. Explicit :page_size and :margin options override @page.

Page declarations without an effect

Only size and page-margin declarations that can be normalized to the formats above change the output. The parser also accepts these page-context declarations without applying them:

These declarations leave earlier applicable page settings, explicit render options, or library defaults in effect. For example, this rule is accepted but does not rotate the page or apply a percentage margin:

@page { page-orientation: rotate-left; margin: 10%; }

Use size: A4 landscape to change page orientation and an absolute margin such as 12mm, or pass explicit :page_size and :margin options. Successful rendering alone does not confirm that every @page declaration was applied. Malformed declarations, unknown page properties, and named or selector-based page rules still return errors.

Tables

Table page breaks

Page breaks use measured content height. The printable area is the page height minus its top and bottom margins.

• <thead> repeats when a table continues onto another page and stays with the first body row when both fit. Body rows do not repeat.
• Set break-inside: avoid on each <tbody> to keep its rows together. A group that fits on a fresh page with its heading moves there if needed. Larger groups split between rows. Without this CSS, groups can split even when they would fit on a fresh page.
• With border-collapse: collapse, each page's final cells retain their configured bottom border. border-bottom: none remains absent.

A single row that cannot fit on a fresh page with its heading may overflow; this behavior does not split individual rows. Divide its content into multiple rows or reduce its height before rendering.

See the grouped table example.

Images and backgrounds

Assets and local files

The resolver receives %{reference: reference, kind: kind}, where kind is :image, :background_image, or :font.

The renderer never downloads remote assets itself. Caller-configured font paths and stylesheet files do not require :base_url. Local image and font reads through :base_url work on Windows, macOS, and Linux. Paths are checked for traversal and existing symlinks before bounded file reads. These checks cannot prevent another process from changing a path during a read. Use asset directories that untrusted users cannot modify, or supply approved bytes with :assets or :asset_resolver. Explicit file mappings, configured font paths, and stylesheet paths also use bounded reads and trust the caller's pathname.

See image and asset examples.

Fonts and text

Choose a font with CSS font-family or the :default_font render option.

Installed fonts must meet the same font-format and embedding requirements as supplied fonts. For consistent font selection across machines, supply your fonts and set system_font_discovery: false. See Register a font.

Missing characters use available fallback fonts, then U+FFFD replacement. Set unsupported_glyphs: :error to fail instead of replacing them.

The renderer subsets TrueType fonts and compresses eligible PDF streams by default. Subsetting keeps glyph IDs unchanged and includes the outlines needed by composite glyphs. Fonts whose license forbids subsetting remain fully embedded. Set subset_fonts: false or compress_streams: false when render time matters more than output size.

Pagination

Pages break automatically or at supported CSS page breaks. Use :page_furniture for running headers, footers, and page numbers. Reserve enough margin for the templates; they do not push body content out of the way.

Templates can vary on the first, odd, and even pages. A matching false or nil variant hides that template. See headers and footers. For PDF viewer bookmarks, see outlines from headings.

Known limits

See Resource limits for configurable size limits and Browser rendering for visual tolerances.

JPEG validation

The renderer accepts 8-bit baseline and progressive JPEGs. Before embedding an asset, JpegValidator checks segment bounds, quantization and Huffman tables, scan component selectors and parameters, progressive scan order, restart marker order, and end-of-image termination. Every scan must contain entropy-coded bytes, and every frame component must have an initial scan. Header-only images, empty scans, and truncated marker streams return an :invalid_document diagnostic at the :style stage through HtmlToPdf.render/2.

These checks validate the encoded structure without decoding the Huffman-coded pixels. They do not prove that the entropy data supplies every declared pixel. PDF readers decode the original JPEG bytes through the DCTDecode filter.

JPEG color conventions

JPEG metadata preserves grayscale, RGB, YCbCr, ordinary CMYK, Adobe CMYK, and Adobe YCCK separately. Frame components and Adobe markers must be consistent. Unsupported component identifiers without an Adobe marker, conflicting markers, and repeated frames fail with a diagnostic. Ordinary CMYK keeps its sample polarity; Adobe CMYK and YCCK use inverted samples. The PDF writer emits explicit DCT color-transform parameters for the supported conventions.

The ordinary CMYK fixture contains standard non-inverted CMYK samples and no Adobe marker. It is independently rasterized alongside Adobe CMYK and YCCK. Some browser JPEG decoders assume inverted samples even without the Adobe marker, so browser decoding alone is not an oracle for ordinary CMYK polarity.

The mapping follows the Adobe PDF reference, section 3.3, DCTDecode filter parameters: https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/pdfreference1.7old.pdf

See PNG and SVG images for output behavior and image errors.