HTML and CSS support

View Source

Render static reports, invoices, forms and labels. Start with the examples. Unsupported features return diagnostics.

HTML support

ContentSupported
TextHeadings, paragraphs, sections, inline formatting, quotations and preformatted text
ListsOrdered, unordered and description lists, including nesting and numbering
TablesCaptions, column/row groups, spanning cells and repeated headings
ImagesPNG, JPEG, SVG and responsive picture/srcset/sizes selection
LinksURI and same-document fragment destinations, including static image maps
FormsInitial artwork and supported editable PDF fields
Embedded documentsAuthorized local HTML, plaintext and supported images; iframe srcdoc
MathNative MathML equations

HTML must be UTF-8. Close nonvoid elements by default; html_recovery: true accepts supported omitted closing tags and nonvoid trailing slashes. JavaScript, event handlers and linked stylesheets are excluded. Supply CSS through :stylesheets.

Rendering checks the supported subset, not complete HTML validity.

Visibility and composition

Supports initial disclosure states, hidden/inert content, declarative shadow roots, slots and named template replacement. Scripts and later DOM updates do not run. Hidden or replaced source content still requires valid, authorized resources.

Forms

Text inputs, textareas, checkboxes, radios and supported selects become editable fields. Buttons stay artwork; hidden inputs produce no output. Use forms: :static for artwork only. Other input types have restrictions; mutable sliders and temporal pickers are unsupported. See PDF forms for names, values and filling.

Supported child-document controls remain editable but cannot repeat across pages or page furniture. Unsupported widget transforms return diagnostics.

CSS support

AreaSupported
SelectorsTags, classes, IDs, attributes, descendants/children, positional selectors, :lang(), simple :not() and initial control states
StylesCascade, inheritance, !important, custom properties, var() and currentColor
LayoutBlock, inline, inline-block, flex, grid, sizing, margins, padding and gaps
TextFonts, alignment, spacing, wrapping, whitespace, list markers and solid text decorations
BoxesColors, borders, rounded corners and background images
Generated content::before, ::after, strings, attr(), counter() and counter reset/increment/set controls
PrintingPrint media queries, bare @page size/margins and page breaks

Support is a subset of browser CSS. Common body lengths include pt, px, mm, cm, in, rem and supported percentages.

Ordinary HTML text paints Unicode line/paragraph separators as spaces, matching Chromium. Ordinary newlines follow white-space.

Positioning and transforms

Static, relative and absolute positioning and 2D transform lists are supported. Transforms move artwork without reflowing surrounding content. Fixed positioning is limited to MathML owners and static popover artwork. Floats, 3D transforms, perspective and animations are unsupported.

Render options

Pass options to HtmlToPdf.render/2 or render_file/3.

OptionDefaultUse
:page_size:a4Named size, orientation tuple, dimension string or numeric tuple
:margin0Points, CSS string or side map
:html_recoveryfalseEnable supported HTML recovery
:stylesheets[]List of {:css, css} or {:file, path}
:base_urlNoneURL resolution base; a local directory also authorizes assets beneath it
:assets%{}Map references to {:bytes, bytes} or {:file, path}
:asset_resolverNoneCallback supplying approved asset bytes
:print_viewportPage-derivedPositive {width, height} in CSS pixels
:image_selection_density1Positive responsive-image density
:default_font"DejaVu Sans"Family name or fallback list
:fonts[]Font definitions with :family and :path or :data
:system_font_discoverytrueLook up installed fonts
:unsupported_glyphs:replaceReplace missing characters or use :error
:compress_streamstrueCompress eligible PDF streams
:subset_fontstrueEmbed only needed TrueType outlines when permitted
:forms:interactiveEditable fields or :static artwork
:metadataHTML titleDocument information such as title and author
:outlinesDisabled:headings or an explicit bookmark list
:page_furnitureDisabledHeader/footer templates and page-number tokens

Page size and margins

SettingExamples and limits
Page size:a4, :letter, {:a4, :landscape} or "100mm 60mm"
Numeric sizesBoth values ≤ 20: inches; otherwise points
Margins36, "18mm 12mm" or %{top: 36, bottom: "12mm"}
@pageSupported size and absolute margins only; explicit options take priority
Ignored page settingsRotation, marks, bleed, decoration and unsupported size/margin values

Tables

FeatureSupport
LayoutAutomatic/fixed sizing, nested tables, separate/collapsed borders
Spanscolspan and rowspan; rowspans stop at row-group boundaries

Automatic tables can exceed their CSS width when cell contents need more space. The renderer preserves text size and does not shrink the page to fit; content beyond the page edge is clipped. Use a wider page or reduce content widths. Compared with v1.0.0, columns now preserve their minimum content widths instead of squeezing them and overlapping text. Existing narrow-page templates may therefore wrap differently or extend farther beyond the page.

Table page breaks

ContentBehavior
<thead>Repeats in ordinary tables
<tbody>break-inside: avoid keeps fitting groups together; larger groups split between rows
Individual rowsNever split; oversized rows may overflow
Oversized inline-block tablesSlice across pages without repeating headings

Grouped table example.

Images and backgrounds

FeatureSupport
FormatsPNG, JPEG and rasterized SVG; image restrictions
SVG text and linksText becomes pixels; internal links are inactive
Image stylingobject-fit, object-position
BackgroundsSizing, positioning and repetition

Assets and local files

SettingBehavior
Resolution order:assets → authorized local files → :asset_resolver; no fallback on resource limits
Local filesRequire a directory :base_url; render_file/3 does not infer it
Path checksTraversal and symlinks checked; use trusted directories or approved bytes
Explicit file pathsCaller-configured asset mappings, fonts and stylesheets are trusted
Other sourcesSupported data URIs; remote resources are never fetched
Resolver request%{reference: reference, kind: kind}; kind is :image, :background_image or :font
Resolver return{:ok, bytes}, :not_found or {:error, reason}
Callback executionDisposable operation worker; shares operation limits

Asset examples.

Resolver process context

When upgrading from v1.0.0, update callbacks that depend on the calling process. self() identifies the worker, caller process dictionary entries are not inherited, and private ETS tables remain accessible only to their owner.

Read needed values in the caller before creating the callback, then capture those values in its closure. Capturing a private ETS table identifier does not grant the worker access. Capture the caller PID before rendering when a callback needs to send it messages.

The logo resolver example reads logo_png before rendering and captures the bytes. For caller-stored images, replace that read with Process.get(:logo_png) or a caller-side ETS lookup.

Fonts and text

SettingSupport
DefaultDejaVu Sans; installed-font discovery enabled
Consistent outputSupply fonts and set system_font_discovery: false
Custom fontsEmbeddable static TrueType; registration example
Missing charactersFallback fonts, then replacement; use unsupported_glyphs: :error to fail

MathML in HTML

FeatureSupport
EquationsTokens, operators, fractions, radicals, scripts, limits, accents and matrices
FontsBundled STIX Two Math; custom fonts need required MATH metrics
Page breaksEquations stay together; oversized equations return a diagnostic

MathML examples.

Pagination

FeatureSupport
BreaksAutomatic or supported CSS page breaks
Headers/footersFirst/odd/even variants; reserve space in page margins
Page numbers{{page}} and {{pages}} in templates

Header and footer examples.

Known limits

UnsupportedAlternative
JavaScript, media playback, canvas drawing APIsStatic HTML and images
Embedded PDFs, XFA, JavaScript form actionsSupported HTML and PDF forms
Named pages, page-margin boxes, CSS page countersPage options and header/footer templates
WOFF/WOFF2, variable fonts, CFF OpenTypeEmbeddable static TrueType fonts
Complex shaping, bidirectional text, vertical writingA renderer supporting those scripts and layouts

Embedded content and framesets have restricted static support. SVG, control styling and some layouts can differ from browsers. Check your generated PDF.

Resource limits · Diagnostics.