Text and fonts
Emoji do not render in the PDF
Emoji appear as boxes, as question marks, or as flat black-and-white outlines where you expected colour.
What is actually happening
Emoji need a dedicated font, and colour emoji need one in a colour font format. Server images almost never have one installed. The monochrome-outline version of the symptom means a font with emoji glyphs was found but not a colour one.
Confirming it is this and not something that looks like it
If everything else renders and only emoji fail, the font stack is the cause and not the encoding.
The fix
Either load an emoji font explicitly, or replace emoji with inline SVG. For a business document the SVG route is usually better anyway, because it renders identically everywhere and does not depend on colour font support in whatever opens the file.
@font-face {
font-family: "Noto Color Emoji";
src: url("https://assets.example.com/fonts/noto-color-emoji.woff2") format("woff2");
unicode-range: U+1F300-1FAFF, U+2600-27BF, U+FE0F;
}
.document {
font-family: "Brand Sans", "Noto Color Emoji", sans-serif;
}If that was not it
These produce the same symptom often enough to be worth ruling out before assuming the fix above did not work.
- Colour font support, which varies by rendering engine even when the font is present
- Emoji with skin tone or ZWJ sequences, which need the composed glyph and fall apart into components without it
- A subset font that dropped the emoji ranges
- Emoji in a header or footer template, which has its own separate font stack
Frequently asked
Does this happen with every rendering engine?
The behaviour behind it is not specific to one tool. Emoji need a dedicated font, and colour emoji need one in a colour font format. Anything rendering HTML to a paged medium has to make the same decision, so the fix travels with you if you change how the render happens.
Will this show up as an error in my logs?
No, and that is what makes it expensive. A document that renders wrong is still a successful render as far as every log line is concerned. It is found by someone opening the file, which is usually the customer.
Related failures
Problems people arrive at from the same starting point, or mistake for this one.
Custom fonts fall back to a default in the PDF
The font file was not fetched.
Text in the PDF cannot be selected or searched
The text is not text.
Line breaks in the PDF differ from the browser preview
The font is not the same.
Chinese, Japanese or Korean characters show as boxes
The font in use has no glyphs for those characters, and no font on the render machine does either.
Arabic or Hebrew text renders backwards or disconnected
Two separate problems.
CSS for paged documents, and what actually works
Which parts of the paged media specification a browser-based render implements.
Everything that goes wrong, by category
The full list, grouped by where in the pipeline it breaks.
Paste your markup and see the rendered document, without signing up.