Vector and raster
Suppose one template produces a certificate. You want a PDF to print or email, an SVG to drop into a web page, and a PNG or WebP for a social post. These outputs come from the same HTML and CSS, but they are not the same kind of file.
PDF and SVG preserve vector elements, so lines and shapes stay sharp at any zoom. Any photo you place inside them is still made of pixels, though. PNG and WebP are raster: a fixed grid of pixels. Zoom in far enough and they go soft, so pick the pixel dimensions for where the image will be shown.
| Format | Kind | Pages | Text | Best for |
|---|---|---|---|---|
| PDF, paginated | Vector | Many, with @page | Selectable, searchable, embedded fonts | Print, archives, attachments |
| PDF, continuous | Vector | One tall page | Selectable, searchable | Receipts, long single sheets |
| SVG | Vector | One canvas | Drawn as glyph outlines | Badges, diagrams, web embeds |
| PNG | Raster, lossless | One canvas | Pixels | Sharp text and flat colour, transparency |
| WebP | Raster | One canvas | Pixels | Smaller files for photos and previews |
Sizes and pixels
Every render takes a width, and paginated PDF also a height, in CSS pixels, the same unit your stylesheet uses: 96 to the inch. An A4 page is 794 × 1123 CSS pixels, a US Letter page 816 × 1056. For a paginated PDF those numbers only set the starting viewport, since @page size wins; for the other formats they are the size of the output.
// A social card: exactly 1200 × 630
const png = await renderer.render({ html, css, format: "png", width: 1200, height: 630 });
// The same template as a printable certificate
const pdf = await renderer.render({
html, css, format: "pdf", width: 1123, height: 794,
options: { pagination: true, pdfTitle: "Certificate of completion" }
});Raster output has one pixel per CSS pixel. A 1200 × 630 render is a 1200 × 630 image; if it must stay sharp on a high-density screen, design the template at twice that size rather than scaling the image up afterwards. Leave the height out for continuous formats and it follows the content, which is what you want for a receipt but not for a card that must fit a fixed slot.
What each format is good for
Use PDF when the document will be printed, archived or sent as a file. Palatine embeds subset fonts in the PDF, meaning only the glyphs the document uses, so the file does not depend on fonts installed on the reader's machine. Text stays selectable and searchable, links stay clickable, and pdfTitle and pdfAuthor fill in the document properties that viewers and search indexes show.
Use SVG for a single graphic that should scale, such as a badge or a diagram. Its text is drawn as glyph outlines: it looks identical everywhere and needs no font on the viewing side, but it cannot be selected or found by search. If the words matter to search engines or screen readers, keep them in the surrounding HTML too.
Use PNG or WebP for things like preview cards and thumbnails, where a plain image is what the destination wants. PNG keeps text and flat colour crisp; WebP usually makes smaller files, especially with photos. Check which formats the destination accepts, and compare PNG and WebP on your own artwork before you choose.
Backgrounds and media queries
Two surprises catch most people the first time they render images. First, PNG, WebP and SVG have a transparent background unless the page paints one. Some viewers show transparency as black, so a black-on-transparent certificate can look blank. Set a background in CSS on html, or pass backgroundColor:
options: { backgroundColor: "#ffffff" }Second, one template often serves screen and print. mediaType chooses which @media rules apply, so a single stylesheet can hide the navigation and switch to print colours for the PDF while the PNG preview keeps the screen look:
@media print {
nav, .share-buttons { display: none; }
body { color: #000; background: none; }
a { color: inherit; text-decoration: none; }
}Fonts and resources
All formats draw text with the fonts you pass in or load with @font-face, so a PNG and a PDF of the same template use exactly the same letterforms. For PDF, TrueType and WOFF fonts are embedded compactly; CFF-based .otf fonts and synthetic bold or italic are embedded as outlines, which still prints correctly but makes larger files.
Resources that fail to load, such as an image with a wrong URL, stop the render by default (missingResources: "error"). That is deliberate: a certificate without its logo is worse than no certificate. Switch to "ignore" only when a missing image is acceptable, and watch the warnings.
Limits to plan around
Palatine does not execute JavaScript, so anything that depends on a script to build the page, such as charts drawn in the browser, must be rendered to HTML or SVG before it reaches Palatine. It also does not produce tagged PDF, so do not rely on it for documents that need that structure for accessibility compliance.
The four outputs serve different layouts. Palatine’s paginated PDF mode supports page margins, running headers, footnotes at the foot of the page and page counters. Continuous PDF, SVG, PNG and WebP use a continuous canvas instead: margin boxes are dropped and footnotes become endnotes. Render every format you plan to ship with real content and inspect each result. The same choices apply offline, in native or WebAssembly builds, and through the hosted API.
Explore the rendering documentation