HTML & CSS Support

PeachPDF renders a subset of the HTML and CSS specifications. This page documents exactly what is and is not supported. Where a feature is only partially supported, the specific gaps are noted.

Forward compatibility

Only standards-compliant documents are guaranteed to keep rendering the same way across PeachPDF versions. As support grows, PeachPDF moves toward what the specifications say — so a document written against the standard keeps working, and gets better as gaps close.

A document that relies on anything outside the standard carries no such guarantee. That includes a value or property PeachPDF happens to accept today but the relevant specification does not define; behavior that falls out of a documented gap (for example, laying content out as though an unimplemented property were absent); and quirks of how PeachPDF currently approximates a feature. Any of these may change in a release that brings the affected area closer to spec, and such a change is not treated as a regression.

Where a correction like that has a visible effect, it is called out in the release notes for the version it shipped in.

Length units

All CSS length units resolve through one shared conversion, at their spec-defined physical ratios (CSS Values & Units §6.2) — everywhere: body layout, fonts, borders, backgrounds, images, @page geometry, and SVG.

In particular, px is spec-correct CSS pixels: a 96px-wide element is exactly one inch wide in the output PDF, and a 96×96-pixel image renders at its true CSS size of one square inch — the same as every browser’s print output and other spec-conformant paged renderers. Relative units (em/rem/%) resolve against their usual per-property bases; the font-measured units (ex/ch/cap/ic/lh and their root-element rex/rch/rcap/ric/rlh forms) are read from the used font — see Font-relative units; viewport units (vw/vh/vmin/vmax, and their logical/small/large/dynamic variants) are supported against the PDF page box — see CSS Viewport Units.

Font-relative units

The units below are defined by the font, per CSS Values and Units 4 §6.1. Each is measured from the font the element actually uses — the first family in its font-family list that resolves — rather than being a fixed fraction of font-size, so 10ch in a monospace font and 10ch in a proportional font are different widths.

The measured units are accepted everywhere a <length> is, including inside calc(), gradient stop positions and radii, and SVG and MathML lengths. In font-size itself, and in line-height for lh, they refer to the parent’s font and line-height (the element’s own is what is being computed), as the specification requires.

A context with no font of its own — a media query or an @page margin, size or margin-box length — has nothing to measure, so there each unit takes the fallback in the last column (and cap and lh use 0.7em and 1.2em).

Nesting depth

Layout, painting and the SVG renderer walk the document tree recursively, so how deep a document may nest depends on the stack of the thread that renders it. A document nested deeper than that stack allows (roughly 100 to 150 levels of <div> on a 1 MB stack, the default of a Windows thread and of a WebAssembly host, and a few dozen on the 512 KB stack of a macOS secondary thread) fails with an HtmlRenderException instead of ending the process with a stack overflow. Elements nested more than 400 levels deep are refused when the HTML is parsed, whatever the stack. color-mix() operands nested more than 32 levels deep make the colour invalid, like any other value that cannot be read. Run the render on a thread with a larger stack to allow deeper documents.

HTML Elements

Global attributes

Document Structure

Metadata

PDF metadata extraction

PeachPDF automatically extracts standard HTML metadata elements and writes them to the PDF info dictionary. No additional configuration is required — just include the elements in your HTML <head>.

The Producer and Creator fields both default to PeachPDF {version} when no <meta name="generator"> is present. The Producer field always identifies PeachPDF as the PDF converter regardless of any generator meta tag.

Example:

<!DOCTYPE html>
<html>
<head>
  <title>Quarterly Report</title>
  <meta name="author" content="Finance Team">
  <meta name="subject" content="Q1 2025 Results">
  <meta name="keywords" content="finance, quarterly, report">
  <meta name="date" content="2025-04-01">
</head>
<body>
  <!-- document content -->
</body>
</html>

Sections

Content Grouping

Headings

Inline Text

Tables

Embedded Content

Forms

Form elements are rendered as static boxes by default. There is no interactive behavior unless interactive PDF forms output is explicitly enabled — inputs cannot be focused or edited, and forms cannot be submitted.

Scripting

Legacy Frames

Malformed markup

The HTML Standard’s tree-construction error-recovery rules change the element tree a stylesheet then matches against — most visibly through the sibling combinators + and ~, and through :first-child/:nth-child(). The body of a document follows them for formatting elements, paragraphs, lists, headings and buttons; tables, <select>, <template> and the <html>/<head>/<body> skeleton follow the standard’s insertion modes.

• Misnested formatting elements (a, b, big, code, em, font, i, nobr, s, small, strike, strong, tt, u) follow the adoption agency algorithm: <b>1<p>2</b>3</p> is a bold 1, then a paragraph with a bold 2 and an unbold 3. A formatting element that is still open when its container ends is reopened in the content that follows — <p><b>a</p>b is bold in both places — up to three identical copies at once.
• A start tag closes the paragraph it cannot sit in, wherever that paragraph is open in button scope: <p><span><div> ends the <p>, so the <div> is its sibling.
• An end tag only closes an element that is in scope. </div> inside a table cell cannot reach a <div> outside the table, and a </span> with a <div> open inside the <span> is ignored.
• An end tag whose element is not open is ignored, and the insertion point does not move. Content after it stays where it was rather than being reparented.
• Table parts are implied and kept in place. <table><tr> gets a <tbody>, a <td> outside a row gets a <tr>, a <col> a <colgroup>, so table > tbody > tr matches; a <td>, <tr> or <caption> outside a table is dropped. Text and elements a table cannot hold (<table>x<tr>…, <table><div>) are moved in front of it (foster parenting). In a <select>, options close each other and anything but options, option groups and text is dropped.
• The document skeleton is supplied. The <html>, <head> and <body> elements the source leaves out exist, <title>, <meta>, <link>, <style> and <script> before the body go into the head, a repeated <html> or <body> only adds its missing attributes, and text or elements after </body> or </html> still go into the body.
• <template> contents are parsed by their first tag (a <tr> as a row, a <td> as a cell) and are not rendered.
• <svg> and <math> end at an HTML element that cannot be inside them (<svg><p> ends the <svg>), and SVG element names are given their mixed case (<clippath> is clipPath).
• A line feed that starts a <pre>, <listing> or <textarea> is dropped, and <image> is an <img>.
• A second <form> inside a <form> is ignored, and </form> ends the form without closing what is open inside it.
• </br> is a <br>.
• </p> is the exception: when no <p> is open it generates an empty <p>, immediately closed. This is what the spec requires, and it is observable. An end tag written after a construct that already implied it — <p><table>…</table></p>, where <table> closes the paragraph itself — leaves a real, empty paragraph element behind, so p + table + p matches that element rather than the next authored paragraph.

Not yet the spec’s: a <table> closes an open <p> whether or not the document is in quirks mode (which the engine does not model), the legacy frameset modes, the mixed-case form of SVG and MathML attribute names, and the tokenizer, which is MimeKit’s rather than the standard’s state machine.

CSS Properties

Box Model

Logical box-model properties

The CSS logical box-model properties are supported and resolve to their physical equivalents, per each box’s own resolved direction and writing-mode — following the CSS Writing Modes Level 4 §7.1 abstract-to-physical mapping table. Under the default writing-mode: horizontal-tb / direction: ltr, block-start/-end are top/bottom and inline-start/-end are left/right; a vertical writing-mode rotates block-start/-end onto the left or right edge instead, and direction: rtl flips which physical edge is inline-start/-end within whichever axis is inline for that writing mode (sideways-lr reverses the inline mapping relative to vertical-rl/vertical-lr/sideways-rl).

Each logical longhand keeps its own identity through the cascade and is resolved to a physical edge once the box’s own direction/writing-mode are known, rather than being aliased directly onto a physical longhand at parse time. When a declaration block is serialized back to CSS, the logical longhands are used as declared — a logical shorthand (e.g. margin-block) is never reconstructed from them.

Borders

Borders and backgrounds are painted on the box’s exact fractional position by default. PdfGenerateConfig.SnapBoxDecorationsToCssPixels opts in to rounding each edge of the box’s decorations to a whole CSS pixel, as a browser does, so a 1px border covers one device pixel at 100% zoom. Border widths are used as written by default (a 0.5px border is drawn 0.5px wide, where a browser draws 1px). PdfGenerateConfig.SnapBorderWidthsToCssPixels opts in to the snapping CSS Values 4 describes, rounded on the CSS pixel since a PDF has no device pixel.

How each border style is drawn

CSS 2.1 §8.5.3 defines what each keyword means but leaves the exact rendering to the renderer. PeachPDF draws them to match what a browser produces, so a document proofed in a browser prints the same way:

• dotted paints round dots whose diameter is the border width, and dashed paints dashes twice the border width. In both cases the ideal gap is one border width, but the gap is then stretched or squeezed so that a whole number of dots/dashes spans the edge exactly — the pattern always begins and ends flush with the corner rather than being cut off part-way through. Because the fit depends on the edge, the spacing changes slightly as a box’s width or height changes, and an edge’s horizontal and vertical runs may use slightly different gaps. An edge too short to hold two dashes is drawn solid. For square-cornered outlines and borders with matching patterned sides, translucent dots and dashes are composited once across adjoining edges, so their corners have the same opacity as the straight runs.
• double paints two lines with a gap between them, each exactly one third of the border width.
• groove and ridge each paint two halves of the border: groove draws its outer half as inset and its inner half as outset, and ridge does the reverse.
• inset and outset shade one pair of sides darker and the other lighter. inset darkens the top and left and lightens the bottom and right; outset is the mirror image. Both ends of the lightness range are special-cased so the bevel never disappears into itself: a color too dark to darken visibly lightens both faces instead, by differing amounts, while a color too light to lighten visibly keeps the declared color on the lit pair rather than being clipped to white.

On a border-collapse: collapse table inset and outset are drawn from the same two faces but pick between them differently, because a collapsed grid line is not any one box’s edge: it straddles the boundary shared by whatever lies on either side of it, so it shows both faces at once, one per half. The half at the smaller coordinate (the left half of a column line, the upper half of a row line) takes the face a bottom or right edge would, and the half at the larger coordinate the face a top or left edge would — on every line alike, interior or outermost, whichever cell’s, row’s or table’s declaration won it. A collapsed inset therefore draws the same two bands as a ridge, and a collapsed outset the same as a groove, which is what a browser paints for the same table. groove and ridge themselves are unchanged by this: they already draw two halves, and the rule above happens to pick the same two faces in the same order a box edge does, so they look identical either side of border-collapse. A page box’s or page-margin box’s border has four real sides and so follows the per-side rule above instead, and mitres at its corners the same way an element’s does.

Where two collapsed grid lines cross, the square they share is painted whole by one of them, and never split along a diagonal. The wider line takes it; at equal width, the one whose style ranks higher in §17.6.2’s order (hidden, double, solid, dashed, dotted, ridge, outset, groove, inset); and failing both, the row line, except on the table’s first row line, where the column line takes it unless that column line is the one at the table’s inline start (its leftmost, in a left-to-right table). The four corners of the table are crossings like any other and are filled accordingly, rather than left blank. This is what a browser paints for the same table; CSS 2.1 resolves a border per grid-line segment and says nothing about the square two crossing segments share. The one case where a square is still shared is a crossing where a line’s own resolved border changes from one side of it to the other — the two runs meeting there split it between them rather than one taking it whole.

A collapsed table’s own border box contains each outermost grid line whole. §17.6.2 instead puts only half of it inside (“the width of the table includes half the table border”), which paints the other half outside the table — over whatever precedes it, or clipped away entirely at a page or container edge, so an outer line comes out thinner than an interior one. PeachPDF follows browsers here, so no part of a collapsed border is ever painted outside the table it belongs to: a 2×2 table of 60×40px cells whose every border is 20px occupies exactly 180×140px — 20 + 60 + 20 + 60 + 20 across — rather than the 160×120px §17.6.2’s half-line box would give it.

A bevelled border side whose color is currentcolor — which is border-color’s initial value, so this covers every border: 2px inset that names no color — does not shade the element’s own color. It shades a fixed light grey, rgb(238, 238, 238), whose two faces are #9a9a9a and #eeeeee. This matches Chromium, and it is what makes an unstyled <hr> and a bare border: 2px inset look the way they do in a browser rather than shading black text into a black-on-black frame. Consequences worth knowing: color has no effect at all on such a border, a translucent or transparent color does not make it translucent, and naming the color explicitly (border: 2px inset #808080) opts back into shading that color — a different result (#2c2c2c over #d4d4d4) from the same grey left implicit. Elements with a table display type (table, inline-table, table-row, table-cell, and the rest) are exempt and do shade their own currentcolor. outline-color and column-rule-color are never substituted this way, even when their own style is bevelled — only the four border-*-color longhands are.

Because currentcolor is resolved per element rather than once during the cascade, a border-color: inherit inherits the keyword itself, not the parent’s resolved colour — so the child resolves it against its own color, and against its own bevel base if the child’s border style is bevelled. A child with no color of its own inherits one, so it usually matches its parent anyway; a child that sets color does not.

Every style mitres into its neighbours at the corners, including each individual line of a double border and each half of a groove/ridge, so adjacent edges of differing width or color meet on the corner’s diagonal — and the mitre follows the line from the border box’s outer corner to its inner corner, so it stays correct when the two sides differ in width and the cut is not 45°. This is what makes the classic zero-size “border triangle” work. outline-style uses all the same rendering, banded outward from the border edge — an outline is drawn exactly as a border of the same width would be on the rectangle that outline-offset + outline-width inflates the border box to, so a dotted/dashed outline fits its pattern to that outer rectangle’s sides and a dot lands in each of its corners. A large negative outline-offset shrinks the outline into the border box, but its outside shape remains at least twice the outline width in each dimension so the outline stays visible.

With border-radius, a border whose four sides share a style, color and width follows the curve as one continuous outline, which keeps the corners seamless and lets a dotted/dashed pattern be fitted to the whole perimeter so it runs evenly all the way round. double is drawn as two such outlines at its thirds; groove and ridge are drawn as two curved half-width bands, with their per-side bevel colors meeting through each corner.

Non-uniform rounded borders share the same curved corner-transition geometry across every style. The transition follows the ratio of the adjoining widths, as allowed by CSS Backgrounds and Borders §4.4: solid and shaded sides fill their part of the curve, each double line and groove/ridge half keeps its own band, and a dotted/dashed centerline is clipped to its side’s part of the corner. On an unsliced box, every patterned side is phased against the complete rounded centerline before clipping, like a browser. This means a small size change can move a dot or dash across a corner transition: a dot may visually join the adjacent side at one size and sit wholly within its own side at another. Sliced fragments instead fit each remaining open side independently and leave a square end where a physical edge is omitted rather than closing a false rounded corner.

Border Radius

Percentages are relative to the border-box width (horizontal radius) and height (vertical radius). Overlapping adjacent radii are automatically reduced proportionally per the CSS spec.

Border Image

The source image is sliced into nine regions per the standard algorithm: the four corners are placed unchanged (scaled independently on each axis to fit border-image-width, but never tiled); the four edges are stretched or tiled along their one free axis per border-image-repeat; the center is painted, tiled the same way on both axes, only when fill is declared. An SVG source is sliced at its own intrinsic size — its width/height, or the viewBox they default to — so the artwork keeps its own proportions, exactly as <img src="frame.svg"> would draw it. A gradient, or an SVG that declares no size at all, has no intrinsic size to slice against and is rendered at the size of the border-image area itself (the border box, extended by border-image-outset) instead; border-image-slice percentages on such a source are therefore relative to that area. On any vector or generated source, a bare <number> in border-image-slice counts CSS pixels of that source, not PDF points. Repainting the same SVG source at the same size reuses one document-local Form XObject, including across pages. Once border-image-source resolves to a real, loaded image, it replaces border-style’s own stroke entirely for that box; an unset or failed-to-load source falls back to painting the ordinary border as if border-image were never declared.

Known limitations:

• Slice regions are sampled without smoothing (nearest-neighbor). A region is cut out of the source with a clip, and a smoothing sampler bleeds the neighboring region’s pixels across that cut — at the scale factors a small texture stretched over a border reaches, a visible fraction of the whole frame. A raster source stretched far past its own resolution therefore shows its pixels rather than a smooth ramp; a vector source is unaffected.
• border-image-outset accepts a <percentage> component (resolved against the same side’s own border width) — broader than the specification’s <length> | <number> grammar, a pre-existing behavior at the parsing layer.

Outline

Unlike border, outline is layout-neutral: it never participates in box sizing, is drawn entirely outside the border edge (offset by outline-offset), and can visually overlap sibling content without shifting anything. It is also drawn on top of that sibling content, following CSS Positioned Layout 4’s painting order. An outline paints over the in-flow content, floats, and z-index: auto/0 positioned boxes of its stacking context. It paints under that stacking context’s positive-z-index content, so a raised overlay covers an outline beneath it, as in Chromium. Browsers differ here: Firefox draws outlines over positive-z-index content as well. There is one deliberate difference from Chromium: Chromium also draws outlines under z-index: auto/0 positioned boxes, which PeachPDF paints under the outline, so a following position: relative sibling cannot cover a ring. Replaced elements (<img>, inline <svg>, <object>, <video>, <iframe>, <math> and form controls) take an outline like any other box, drawn around the border box after the element’s own content. A positioned box, float, inline-block, or flex or grid item paints as one unit: it draws the outlines inside it before any later content paints. With border-radius, the outline follows the curve too: each corner radius expands outward by the same outline-offset + outline-width its rectangle itself expands by, matching Chromium’s rounded-outline geometry — CSS Basic User Interface 4 leaves the exact treatment as a UA choice, but rounding to match is the one most browsers make.

When an inline element wraps across multiple lines, its outline is drawn as one connected shape around all of them rather than leaving the two line-wrap edges open the way border/background do under box-decoration-break: slice (the default) — CSS Basic User Interface 4 recommends a fragmented outline be fully connected rather than open on some sides. The shape is the outline of the region the lines’ rectangles cover once outline-offset has been applied to each of them: where consecutive lines touch or overlap — which is what a border, extra padding, or a positive outline-offset on a wrapped inline typically causes — they merge into a single stepped contour, with the outline running around its concave corners rather than closing across each wrap. Lines that don’t touch stay separate pieces of the same shape, which is how an ordinary widely-spaced wrapped inline still reads as one ring per line. This matches Chromium, which builds the same region the same way.

Every outline style follows that shape, including the patterned and bevelled ones. On a square-cornered contour, dotted and dashed fit their pattern along each straight edge, so a dash lands on every corner it turns, including the concave ones a merge introduces; a rounded one has no corner for a dash to land on, so it is fitted to the closed contour as a whole, which spaces the pattern evenly all the way round rather than restarting it at each corner. groove, ridge, inset and outset pick each edge’s light or dark face from the direction that edge runs in rather than from which side of a box it is — the only rule that is still well defined once the lines have merged and a “side” no longer is. Both match what Chromium does for the same content.

For translucent square-cornered dotted and dashed outlines, each corner dot or dash is painted once, so the corners have the same opacity as the straight runs. The same applies to borders with matching patterned sides.

The border boxes of the non-inline boxes inside an inline (images, inline-blocks, floats) join the region too, so an outline around content taller than its own line box goes around it, as in Chromium. Out-of-flow boxes and list markers do not.

A page or column break is a different axis and is unaffected by any of this: the region is always built from one page’s own rectangles, so a box broken across pages gets its own shape on each, and the block-axis edge the break cuts through stays open on both sides of it, exactly as border’s own slice geometry already leaves it.

outline-style: auto is a UA-defined appearance, typically used for a browser’s own focus ring. CSS Basic User Interface 4 says the outline-width property is ignored when outline-style is auto, and separately allows a UA to treat auto as solid — the second is a choice about the style, not a licence to keep the author’s width. PeachPDF therefore draws auto as a solid ring at its own fixed width of 2px, whatever outline-width says (including 0), matching the ring Chrome draws. That ring is also centred on the edge outline-offset puts it at, rather than sitting wholly outside it the way every other style does, so with the default zero offset it straddles the border edge by 1px either side — again matching Chrome. If you want an outline of a width you control, use any other outline-style.

outline-color: invert is a legacy value: rather than approximating it with a fixed color, PeachPDF renders it as a true per-pixel color inversion of whatever is underneath the outline, using a PDF blend mode (/Difference composited with white, which is mathematically equivalent to inverting the backdrop). This is a genuine inversion, not a fixed guess at a contrasting color, and it composites correctly regardless of what’s behind the outline at render time.

Box Shadow

The first two lengths are the shadow’s horizontal and vertical offset; the optional third is the blur radius (must be non-negative) and the optional fourth is the spread radius. Multiple shadows are layered, the first-listed drawn last (on top). An outset shadow paints behind the element’s background; an inset shadow paints over the background, clipped to the padding box and fading inward.

Blur rendering: PDF has no blur, so a blurred shadow is drawn into a bitmap at PdfGenerateConfig.RasterizationDpi, Gaussian-blurred, and placed beneath the element. Only the shadow is a bitmap — the element’s own background, border and text stay vector, selectable and tagged — and a shadow is knocked out under the box it belongs to. Under PDF/A-1 or PDF/X-1a/X-3, which forbid the soft mask a blurred bitmap needs, a document using a blurred shadow is rejected, as any semi-transparent shadow always was.

Transforms

3D transforms and perspective

3D transform functions are composed as a genuine 4×4 matrix and projected onto the element’s own flat plane. Without perspective that projection is affine and mathematically exact — translate3d()/scale3d()/rotateX()/rotateY()/rotate3d()/matrix3d() all render as true, lossless 2D transforms of the flattened element, in vector form.

Perspective is not affine, so a PDF transformation matrix cannot carry it: parallel edges stop being parallel and a receding plane foreshortens. An element whose transform involves perspective(), or that is a direct child of a perspective container and has a 3D transform that moves it out of its plane (rotateX(), rotateY(), rotate3d()), is therefore painted into a bitmap in its own untransformed space and warped through the projective map at PdfGenerateConfig.RasterizationDpi (see Rasterized effects); a plane brought closer than its flat size is rendered with proportionally more pixels so it does not blur. A plane parallel to the view plane (translateZ() alone) is only scaled, and stays vector, and so does a perspective so faint that the warp differs from a plain matrix by less than a quarter of a device pixel over the element (a small card on a distant viewer, say). The part of an element that passes behind the viewer is not drawn. A perspective (or perspective()) distance under one CSS pixel is treated as one pixel; zero is none.

• Text in a warped element stays selectable: it is supplied again as invisible text positioned by the transform’s linearisation at the element’s centre, which is exact there and approximate towards the edges under strong perspective.
• Filters, opacity, clip-path and blend modes on a warped element apply to it before the warp, in its own space, as they do without perspective.
• Not modelled. A warped element inside another transformed ancestor is warped in its parent’s untransformed space. Under PDF/A-1 and PDF/X-1a/X-3 the warped bitmap has soft edges and is rejected unless the document asks for flattening.

Shared 3D space (transform-style: preserve-3d). An element whose used transform-style is preserve-3d starts a 3D rendering context: it and every descendant reached through a chain of preserve-3d elements are planes in one space. Each plane’s transform is accumulated down from the context’s root (its own transform about its transform-origin, then the perspective its parent gives its children, then its parent’s whole transform), so a child of a rotated parent rotates with it and a perspective set above the context reaches every plane in it, however deep. Whatever is not itself in the chain (an element with transform-style: flat, or one a grouping property forces flat) is flattened into its plane.

• Otherwise the planes are painted into bitmaps and composed into one picture through a per-pixel depth test at PdfGenerateConfig.RasterizationDpi: a nearer plane covers a farther one whatever the document order, and planes that intersect are resolved exactly where they cross rather than by sorting. Translucent planes blend in back-to-front order of their centres. Each plane honours its own backface-visibility.
• A context whose planes all stay parallel to the view plane at one depth has nothing to resolve, and is painted exactly as it would be without preserve-3d, in vector form. So is one whose planes are only tilted (no perspective) and where, over each overlap, one plane is in front of the other throughout (none pierces another): they are drawn back to front, each under its own matrix, with no bitmap.
• Text stays selectable, as for a single warped element.
• Approximations. A translucent pixel does not hide what is behind it from a plane painted after it (the planes are ordered back to front by their centres, which is exact unless translucent planes intersect each other).

Opacity

Animations

A PDF has no timeline, so in PDF output CSS animations are rendered as a single frame: set PdfGenerateConfig.AnimationProgress (or --animation-progress on the command line) and every animation is sampled at that point, from 0 (its start) to 1 (its end), of its own run. Without it animations are not applied.

A document shown on a screen can play them instead: with HtmlDocumentOptions.AnimationsEnabled a clock runs the animations and transitions over time (animation-delay, animation-fill-mode and animation-play-state apply, and transition runs when a style change restyles a box: a state rule, or a change of class, attribute or preference through the document’s API). The HtmlView control for WinUI does it with AnimationsEnabled. Properties that only paint (transform, translate, rotate, scale, opacity, filter, visibility, colours, shadows, outlines and the like) play with no layout; properties that move or resize boxes (width, margin, top, font-size, flex and grid sizing) play when the host lays the document out for each frame, and so do registered custom properties (@property), which a var() reads. The rest of this section describes how a value is sampled and mixed, which is the same for both.

The values of an animation replace the ordinary ones before layout, in the cascade’s animation origin: above every normal declaration and below every !important one. An !important declaration of a custom property is seen by a var() in an animated property or in a keyframe, and an !important color is the color currentcolor stands for in a mix (an animation of color itself then does not apply, as the declaration outranks it); a color that another animation in the list sets is seen by every animation’s currentcolor. An !important animation-* declaration (animation: none !important, for instance) still decides which animations run. Between two keyframes a value is mixed the way a browser mixes it:

• Mixed: numbers (opacity, flex-grow, z-index as a whole number), lengths and percentages, angles (deg, grad, rad, turn), colors (the next point), and any list or function made of them: the arguments of transform and filter functions, box-shadow, text-shadow, background-position. Lengths of different units (10px to 50%) are written as a calc() and resolved at layout, and so is a calc() against a length or against a calc() of another shape. A bare 0 takes the other value’s unit (against a calc() it does not in line-height, tab-size, border-image-width and border-image-outset, where it is a number, so that pair flips), and normal is the zero length for letter-spacing and word-spacing. currentcolor against a color mixes as the box’s own color in any color property (background-color, border-color, outline-color, column-rule-color, text-decoration-color, …), in a shadow’s colour and in a gradient stop (a color animated in the same keyframes counts, so currentcolor is the text color of the same moment); two values that both say currentcolor keep the keyword, and at the very start and end it stays the keyword. none against a transform or filter list mixes with the identity of each function in the other list. Two transform lists are paired function by function, the shorter list continuing with identity functions: functions that share a primitive pair up whatever they are called (translateX with translate, rotate with rotateZ, scale(1) with scale(2, .5)) and are mixed on their own, so a rotation keeps the angle as written (rotate(0deg) against rotate(360deg) scale(1.2) turns a full time). At the first position where the two share no primitive, what is left of each list is composed to one matrix and the two matrices are mixed through their decompositions into translation, scale, skew and rotation, where a rotation takes the short way round (a full turn is lost). matrix() and matrix3d() are always mixed as matrices, never entry by entry (a pair that cannot be decomposed - a collapsed scale, or perspective terms in a matrix3d() - flips half way; a list with a calc() argument is not paired, but is mixed as two whole matrices). Two perspective() functions pair and mix their lengths. visibility is visible for the whole interval between visible and anything else, and display between none and anything else shows the other value for the whole interval (so a box fading out stays in the layout until the end). A custom property in a keyframe is written onto the element for a var() to read: one that is not registered with @property flips at the middle of the interval, and a registered one is mixed by its syntax (<length>, <number>, <color>…). An !important custom property outranks the animation.
• Colors: hex, named colors, transparent, rgb(), hsl() and hwb() are mixed premultiplied in sRGB, so hsl(0, 100%, 50%) to hsl(120, 100%, 50%) passes through olive, not through the hue wheel. As soon as one of the two is a lab(), lch(), oklab(), oklch(), color() or color-mix() color,, a relative color (rgb(from ...)), or has a component written as none (a missing component, which takes the other color’s value in the mix), the pair is mixed premultiplied in Oklab, as a browser does, so lab(50 40 20) to lab(70 -30 30) and #f00 to oklch(0.5 0.15 260) do not pass through the muddier sRGB middle. A color outside the sRGB gamut (a vivid oklch(0.7 0.3 150), say) is mixed from the values it was written with and clipped to sRGB once, at the end, as a browser does. currentcolor takes part as a legacy color whatever the box’s color is.
• Flipped half way: a value with no way to be mixed (keyword values, auto against a length, two transform lists that cannot be mixed through matrices (see the limitations below), calc() against a value that is not a length) shows the first keyframe’s value until half way through the interval and the second’s after.

Gradients are mixed stop by stop where a browser would flip half way. The -webkit- spellings of the animation and transition properties and @-webkit-keyframes are accepted as the standard ones.

PeachPDF reports prefers-reduced-motion: reduce, because a static PDF has no motion. A stylesheet with the common reset @media (prefers-reduced-motion: reduce) { * { animation: none !important } } therefore switches off every animation, even when AnimationProgress is set.

transition and its longhands (transition-property, transition-duration, transition-delay, transition-timing-function, transition-behavior) run on a screen whenever a style change restyles a box (a change of :hover, :active or :focus state, or of a class, an attribute or the preferences through the document’s API), from the value the box had to the value it now has, and are never run in a PDF: a transition needs a style change to start from, and a document that has just loaded has none (@starting-style gives it one, see below). A transition-property entry may be all, a property or a shorthand that sets it (margin). A property whose values do not mix (display, a keyword) only transitions when its entry says allow-discrete in transition-behavior; display then keeps the box in the layout, with the other value, for the whole interval. A transition that is interrupted starts again from where it had got to, except that a change back to where it started reverses it over the part of the duration already travelled, and a restyle that leaves the transition’s target as it is lets it run on. @starting-style (top level, or nested in a rule) gives an element the style a transition runs from when the document first appears or when the element is shown again after display: none; its rules take no part in the ordinary cascade. Not run: a transition of a pseudo-element (::before), of an inherited property that moves boxes (font-size), or of a property a running animation animates.

Known limitations: the matrix part of a transform mix needs both sides to be a matrix before layout, so a pair with a percentage argument in that part (translateX(50%)), a perspective() against something else, or a collapsed scale (scale(0)) still flips half way; scroll and view timelines follow only the document’s own scrolling (a box with overflow: auto or scroll has no scroll position, so a timeline on it does not exist and its animations have no effect); a registered custom property is mixed only when both keyframe values are of one single interpolable type (<length>, <number>, <integer>, <percentage>, <length-percentage>, <color>, <angle>, a transform), and flips half way otherwise, lists included; the declarative document-building API does not apply animations; CSS animation of the elements of a standalone SVG (<img src="x.svg">) is not applied (those of an inline <svg> are: see CSS animations in SVG); and SVG’s own animation elements (SMIL) are sampled at one point of their span for an inline <svg> (see SMIL animation).

Filters and Blend Modes

opacity() composes into the same isolated-transparency-group alpha the opacity property itself uses (see Opacity above). brightness(), contrast(), and invert() are each an affine, per-color-channel transform — CSS Filter Effects 1 defines every one of them as an equivalent feColorMatrix/feComponentTransfer — so they map directly onto a PDF ExtGState /TR transfer function (ISO 32000-1 §8.6.5.3): real, spec-correct color math evaluated by the PDF reader itself, not a rasterized approximation. Multiple native functions chained in one filter: value still compose into a single transfer function, so a whole native-only filter chain costs one PDF object, the same as one function alone.

Not every PDF reader honours a transfer function: MuPDF, and the viewers and libraries built on it, ignore it and draw the element unfiltered, and PDFium applies it to solid fills and text but not to a gradient or other shading. Set PdfGenerateConfig.PortableColorFilters to write the same three functions as blend-mode layers (Multiply, ColorDodge, Screen, ColorBurn, Difference) that every reader composites itself. The result is still vector content and matches the CSS formulas to within a few of 255 levels on opaque content; where the content is partly transparent (an rgba() colour, an antialiased edge) the colour is slightly off, which is why it is opt-in.

drop-shadow(<offset-x> <offset-y> <std-deviation>? <color>?) draws a blurred, offset copy of the element’s real alpha shape — its glyphs, an image’s transparent corners, an SVG’s outline, a clip-path — in the shadow colour, beneath the element. Unlike box-shadow, the third length is the standard deviation itself, not twice it. It is rendered in the same bitmap as any other raster filter function and applied in list order, so drop-shadow(…) drop-shadow(…) shadows the first shadow too, as the specification describes. A graphics that cannot rasterize falls back to shadowing the element’s border-box rectangle.

Rasterized effects

A few effects cannot be expressed as vector PDF content. A blur needs per-pixel convolution (which also means a blurred box-shadow or text-shadow, and a drop-shadow() that follows an element’s real shape), and grayscale(), sepia(), saturate() and hue-rotate() each mix color channels together, while a PDF can only recolor each channel on its own. For these, PeachPDF renders the element into a bitmap, applies the whole filter list to it in the order it was written, and embeds the result. backdrop-filter is the same idea applied to the content painted behind an element, and an SVG <filter> with a blur, lighting or other pixel primitive is evaluated the same way (see SVG filters). Everything else on the page stays vector.

• Which elements. Any element whose filter list contains blur(), grayscale(), sepia(), saturate(), hue-rotate() or drop-shadow() with an actual effect (blur(0), grayscale(0), saturate(1) and hue-rotate(0deg) change nothing and stay vector). The bitmap covers the element, all of its descendants and its own box-shadow, grown by three standard deviations of every blur() so the blur has room to spread. A brightness(), contrast(), invert() or opacity() written next to one of these functions is applied in the same bitmap pass, in order; on their own they stay native vector math. The element’s own opacity and mix-blend-mode are applied after the filters, as the specifications order them.
• Blur radius. blur(<length>) is the standard deviation of the Gaussian, in the length’s own units. Up to a deviation of 2 device pixels the exact kernel is used; beyond that, the three-pass box approximation Filter Effects 1 specifies for feGaussianBlur.
• Resolution. The bitmap is rendered at PdfGenerateConfig.RasterizationDpi pixels per inch of paper (default 300; 72 to 1200; --raster-dpi on the command line), so it stays sharp when zoomed or printed, up to that resolution. The value is a physical resolution, independent of PixelsPerInch: the bitmap is always placed at exactly the size of the content it replaces, so an inch stays an inch and only the number of pixels behind it changes — with PixelsPerInch = 96 and a value of 288, each CSS pixel is backed by 3 × 3 = 9 bitmap pixels. A region that would exceed PdfGenerateConfig.MaxRasterPixels (64 million pixels by default) is rendered at a lower resolution just large enough to fit; its placed size never changes. Bitmaps are exempt from DownscaleImages. See Rasterized effects and resolution.
• Text. The text of a rasterized HTML element is drawn into the bitmap, and PeachPDF also places the same text over it as invisible, positioned text, so it can still be selected, searched and copied, and tagged-PDF structure still points at it. Text drawn by an inline <svg> or <math> inside the element is part of the bitmap only, and text-decoration lines are not part of the selectable overlay. Small text in a bitmap can be made sharper by the font’s own hinting (TrueType instructions, or the hints of CFF outlines) with PdfGenerateConfig.TextHinting (off by default; it never touches the PDF’s vector text or layout), and CFF fonts can also have their stems thickened with TextStemDarkening, see Sharper small text in bitmaps.
• Anti-aliasing. Every pixel of the bitmap is anti-aliased by default — shape fills, images and text alike. PdfGenerateConfig.RasterAntiAliasing (--no-raster-antialiasing on the command line) turns this off, thresholding every pixel to fully transparent or fully opaque instead; it has no effect on the PDF’s own vector content, which a viewer anti-aliases on its own. See Turning off smoothing.
• Limits. text-decoration-skip-ink is not applied, a CMYK image is drawn through a colour-unmanaged RGB conversion (the PDF keeps its CMYK data everywhere else), and a stroke thinner than one device pixel is widened to one pixel. A document that requests PDF/A-1 or PDF/X-1a/X-3 conformance is rejected if it uses one of these effects, because a bitmap with soft edges needs a transparency soft mask, which those levels forbid.

Backgrounds

Canvas background (<html>/<body>)

Per CSS Backgrounds 3 §2.11.2, the root element’s background doesn’t just paint its own box — it fills the whole canvas (here: every page). PeachPDF resolves this once per document: <html>’s own background (background-color and/or background-image layers) is used if it declares one; otherwise <body>’s background is propagated to the canvas instead; otherwise no canvas fill happens at all. When <html> has a background of its own, <body>’s background is not propagated and paints as an ordinary box background over <body>’s own box. Whichever element was used for the canvas fill isn’t separately re-painted at its own (possibly much smaller than a page) laid-out rect — the canvas fill already covers it. A non-<body>/<html> element’s own background (e.g. a <div>) is unaffected and continues to paint normally. The fill repeats identically on every page the document spans. The @page box’s own background — a further tier below this canvas fill — is documented in @page rule below.

Color & Typography

Per-character font matching and coverage fallback

Font matching is per-codepoint, following the CSS Fonts 4 matching algorithm: each character is resolved to the first family in the font-family list whose face both covers that character (via its @font-face unicode-range, or, for a system/rangeless font, its actual cmap coverage) and contains a glyph for it. A run whose primary font lacks a glyph for some character therefore falls back to the next declared family that covers it, and multiple @font-face rules sharing one font-family but declaring different unicode-range subsets each supply their own characters.

Supplementary-plane (astral) characters above U+FFFF — where nearly all emoji live — are supported: they resolve through the font’s format-12 cmap subtable, both for glyph lookup and for coverage-based fallback, and render the font’s monochrome glyf/CFF outline. A font whose only Unicode subtable is format 12 works too; its groups then answer for the Basic Multilingual Plane as well.

Color emoji is supported for COLR/CPAL fonts (both COLR version 0 and version 1), including the COLR v1 build of Noto Color Emoji. PeachPDF decodes each color glyph and draws its visible artwork as native PDF vector content: COLR v0 layers are filled with their CPAL palette colors bottom-to-top, and COLR v1 paint graphs are composed — solid fills, linear/radial/conic (sweep) gradients, per-paint and per-gradient-stop alpha, affine transforms, glyph clips, and separable/HSL blend-mode compositing. Color glyphs are also searchable and selectable: a subset of the color font is embedded solely for invisible PDF text, with a /ToUnicode map and per-occurrence /ActualText preserving the exact source sequence copied from each glyph (including variation selectors, ZWJ, modifiers, regional indicators, and tag characters). The embedded subset increases file size compared with vector-only color-glyph output; it never supplies visible ink. A color glyph’s artwork itself is stored only once per document however often it is used — including across pages and across font sizes — so a document repeating an emoji pays for the artwork once and for a short placement instruction at each occurrence.

Multi-codepoint emoji sequences resolve to their composed glyph when the font defines one, via the same GSUB path as any other ligature (see Text shaping) — ZWJ sequences (👩‍💻, 🏳️‍🌈), regional-indicator pairs (🇺🇸, 🇯🇵), tag sequences (🏴󠁧󠁢󠁳󠁣󠁴󠁿), and skin tone modifiers (👍🏻 👍🏽 👍🏿, U+1F3FB–U+1F3FF), including a modifier and a ZWJ in the same sequence (👩🏽‍💻). Emoji assigned an ordinary ideographic, emoji-base, or paired regional-indicator line-break opportunity wrap between complete grapheme clusters without requiring overflow-wrap; the sequences listed above remain intact. Other sequences, including keycaps, retain their own Unicode line-break behavior rather than gaining a break merely because they are emoji. A trailing U+FE0F (VARIATION SELECTOR-16) in such a sequence neither draws nor contributes an independent advance, and does not prevent the ligature from forming.

Bitmap color emoji is supported too: the CBDT/CBLC tables (the classic bitmap build of Noto Color Emoji; PNG image formats 17, 18 and 19, every index-subtable format) and sbix (Apple Color Emoji; png and jpg pictures, and dupe redirects). Each glyph is drawn as the font’s own picture, scaled by font-size over the strike’s pixels-per-em and placed by the picture’s bearings; the smallest strike at least as large as the text is used, so a picture is scaled down rather than up. A picture used many times is stored once per document. Text stays searchable and selectable in the same way as for COLR glyphs, and the pictures are drawn by the raster backend too, so an emoji inside a filtered or flattened element is not lost. The pictures have an alpha channel, so a document targeting PDF/A-1 or PDF/X-1a/X-3 needs transparency flattening to use them. tiff and mask sbix pictures, and bitmap formats other than PNG in CBDT (formats 1, 2, 5, 6, 7, 8, 9), are not drawn.

SVG-in-OpenType (the SVG table) is supported: each glyph’s SVG document, plain or gzip-compressed, is rendered through the SVG engine as vector content and shared between occurrences as one form. The glyph is the element with the id glyph<N> (a document that covers a single glyph with no such element is drawn whole); the document’s var(--color0), var(--color1) and so on are the font’s CPAL palette entries (so font-palette applies), currentColor and context-fill are the text colour, and context-stroke is no paint (the text has no stroke), except inside a <use> or a marker, where context paint refers to that element’s own fill and stroke. A font that also has bitmaps or COLR paints uses those first. The document comes from the font file and is untrusted: it is parsed without a DTD, an inflated document is capped at 4 MiB, and only data: images resolve. A document that cannot be used draws the glyph’s outline. Inside a rasterized element (filters, shadows, PDF/A flattening) the glyph is drawn from its document too, at the raster resolution, so the effect sees the real glyph. A glyph is not clipped to the em box: it is drawn on a canvas of at least one em to its left, an em and a half above, two ems to its right and half an em below, grown to hold the shapes it draws (and their strokes) up to eight ems from its origin in any direction. The painted region of a filter, and text and marker content, do not count towards that size, so they are clipped at the canvas. Animation is ignored, since a PDF has no timeline.

COLR glyphs in CFF-flavored (OpenType OTTO) fonts paint exactly like those over TrueType outlines. The Porter-Duff composite modes of a COLR v1 PaintComposite are drawn as vector content from paint order and clipping: CLEAR, SRC, DEST, DEST_OVER, SRC_IN, DEST_IN, SRC_ATOP and DEST_ATOP clip one operand to the other’s glyph outlines, and SRC_OUT, DEST_OUT and XOR clip to the area outside them, along with the separable and HSL blend modes. A radial gradient between two circles honors its inner radius, with different centers too, and concentric circles support repeat/reflect as vectors. The two things a PDF cannot express, a PLUS composite (an additive blend) and a repeat/reflect radial gradient between circles with different centers (a PDF shading can only pad), are drawn by the raster backend: such a glyph is painted once on a pixel canvas, at a 300-pixel em, and embedded as a picture shared between occurrences (the pictures have an alpha channel, so a document targeting PDF/A-1 or PDF/X-1a/X-3 needs transparency flattening to use them), while every other glyph stays vector. Still approximate: the shape an IN/OUT/ATOP/XOR composite clips to is the outline of the other operand’s glyphs, so where those overlap each other and carry partial transparency the overlap is painted twice, and a glyph whose own contours overlap is treated as even-odd when clipping to its outside.

When no family in the declared font-family stack (plus the default font) covers a character, PeachPDF performs a last-resort system-fallback search across every OTHER font registered with the PdfGenerator instance — system-discovered fonts plus anything added via AddFontFromStream — the same final step the CSS Fonts 4 font matching algorithm leaves to the user agent. When more than one registered font covers the character, the one whose own coverage best overlaps the character’s Unicode script wins (so a font built for that script is preferred over one that merely happens to include an incidental glyph); a character with no script of its own (punctuation, digits) or a tie between equally-good candidates falls back to alphabetical family-name order for a reproducible result. A character nothing registered covers still shows a missing-glyph box.

Variation sequences. A variation selector stays in the same run, and the same font, as the character before it. A font’s cmap format 14 (Unicode Variation Sequences) table is read: a sequence the font gives its own glyph (a non-default record — e.g. a slashed zero for 0 + U+FE00, or an ideographic variant) draws that glyph, and for U+FE0E/U+FE0F a listed sequence also counts as the font supporting that presentation (see font-variant-emoji). No variation selector other than U+FE0E/U+FE0F influences which font is chosen.

Text Layout

Text shaping

PeachPDF applies essentially all of OpenType Layout a font can exercise, including Arabic-family complex-script joining, the Universal Shaping Engine (USE) syllable reordering used by Devanagari, Bengali, Gujarati, and Tamil, and Khmer’s own separate coeng/subjoined-consonant shaping: GSUB single, multiple, alternate, ligature, contextual/chaining-context, and reverse-chaining single substitution (including a contextual/chaining-context rule whose own target is another contextual/chaining-context lookup, nested to an arbitrary depth); GPOS kerning, cursive attachment, and mark positioning; a real Unicode Bidirectional Algorithm (UAX #9); Arabic/Syriac-family joining-form resolution and shaping; conjunct/reph formation with syllable-level glyph reordering for the four USE-shaped scripts above; and Khmer’s own coeng-driven subjoined-consonant stacking. Indic script reordering beyond those four USE scripts (other USE-driven Brahmic scripts, e.g. Gurmukhi, Kannada, Malayalam, Oriya, Telugu) is not implemented. In practice:

• Ligatures are formed automatically from a font’s GSUB liga/clig (“common ligatures”) and rlig (“required ligatures”) features — e.g. f + f becomes a font’s ff ligature glyph when the font defines one, the same way a browser renders it, not only when the source text already contains a precomposed ligature codepoint (e.g. fi, U+FB01). font-variant-ligatures controls this: normal (the initial value) and common-ligatures enable liga/clig, none and no-common-ligatures disable them, discretionary-ligatures/historical-ligatures (and their no-* forms) enable/disable a font’s dlig/hlig features the same way, and contextual/no-contextual enable/disable a font’s calt feature — but per spec rlig (“required ligatures”) is never affected by this property, not even by none, since a font’s required ligatures aren’t a stylistic choice.
• Glyph composition/decomposition and localized forms (ccmp, locl) are applied to all text, for every script, without being requested — they are default-on features in the OpenType feature registry, not stylistic opt-ins, so a font that decomposes a precomposed letter into base + mark, or that keeps its emoji-sequence ligatures in ccmp rather than liga, is honored. This matters most for modern color-emoji fonts: Noto Color Emoji’s entire GSUB feature list is a single ccmp record, and that is where its regional-indicator (country flag), tag-sequence, and ZWJ-sequence ligatures live.
• Caps, numeric, East Asian, positional variants, and multiple substitution (font-variant-caps, font-variant-numeric, font-variant-east-asian, font-variant-position, and arbitrary tags via font-feature-settings) apply a font’s GSUB Single, Multiple, or Alternate Substitution features the same way — see the property table above for each one’s specific OpenType tags and fallback behavior.
• Contextual/chaining-context substitution (GSUB lookup types 5/6, calt and any font-feature-settings tag a font routes through one) supports all three OpenType subtable formats (glyph-sequence, class-based, and coverage-based), including a font’s lookupFlag/GDEF mark filtering — an intervening non-participating glyph (e.g. a diacritic) inside the matched backtrack/input/lookahead window is correctly skipped rather than breaking the match, the same way ligature substitution’s own component matching already did.
• Reverse-chaining context single substitution (GSUB lookup type 8) is applied end-to-start, per spec, for the rare font that defines it.
• Default-ignorable characters — variation selectors (U+FE00–U+FE0F, U+E0100–U+E01EF), ZWJ/ZWNJ, the bidi controls, word joiner, the Hangul fillers, and the language tag characters (U+E0000–U+E007F) — draw nothing when the font has no glyph for them, rather than falling through to the font’s missing-glyph box. That is what Unicode’s Default_Ignorable_Code_Point property means, and a font is expected not to cover them. They are still fully visible to shaping first, so a font that does map one (and ligates through it, as emoji ZWJ sequences do) behaves exactly as authored, and a ligature whose component list skips over one — e.g. U+1F3F3 U+FE0F U+200D U+1F308 against a flag + ZWJ + rainbow rule — still forms. U+FE0E/U+FE0F additionally steer font selection between a text and an emoji form — see font-variant-emoji.
• Kerning, cursive attachment, and mark positioning (GPOS) apply a font’s pair/class kerning (kern, gated by font-kerning), cursive joining (curs, requested for Arabic-family joining text — see below), and mark-to-base/mark-to-ligature/mark-to-mark diacritic attachment (mark/mkmk, always applied when the font defines it — not a stylistic opt-out), including contextual/chained-contextual positioning (GPOS lookup types 7/8) nesting any of these.
• Per-language feature selection: GSUB feature selection uses the script’s language-specific LangSys when the element’s resolved language (its own lang attribute, or its nearest ancestor’s, per the HTML “language of a node” algorithm) maps to a recognized OpenType language tag, falling back to the script’s default language system otherwise.
• Arabic-family complex-script shaping (Arabic, and other joining scripts sharing its state machine, e.g. Syriac) resolves each character’s initial/medial/final/isolated joining form from its Unicode Joining_Type/Joining_Group (per UAX #53 semantics) and requests a font’s init/medi/fina/fin2/fin3/med2/isol GSUB features accordingly, ahead of the general ligature/contextual pass (so a font’s own rlig ligatures — e.g. Arabic’s lam-alef — see the already-joining-form-selected glyphs, matching real shaping engines’ own staging) and a font’s curs GPOS feature (cursive baseline attachment, for fonts whose joining relies on it rather than purely on positional substitution). Shaping itself always runs in true logical (source) order — matching real shaping engines — with only the resulting glyph list reversed for right-to-left display, since Arabic is a strong-RTL script and reads right-to-left regardless of the surrounding direction.
• Universal Shaping Engine (USE) syllable reordering (Devanagari, Bengali, Gujarati, Tamil) classifies each character’s Unicode Indic_Syllabic_Category/Indic_Positional_Category into a syllable structure (consonant, conjunct-forming halant sequence, dependent vowel sign, vowel modifier — plus, for Bengali specifically, its own Consonant Placeholder and Syllable Modifier categories, neither reachable from any Devanagari/Gujarati/Tamil codepoint), applies a font’s default glyph pre-processing (locl/ccmp/nukt/akhn), forms reph from a word-initial RA+virama sequence via the font’s own rphf feature, applies the font’s conjunct/half-form/subjoined-form features (rkrf/abvf/blwf/half/pstf/vatu/cjct), then reorders the resulting glyphs — repositioning a formed reph forward past the base consonant, and moving a pre-base dependent vowel sign (e.g. a vowel sign I) backward to immediately follow the base — before a final pass applies the font’s own presentation features (abvs/blws/haln/pres/psts). Gujarati and Tamil need no script-specific classifier/grammar code beyond what Devanagari already exercises; other USE-driven Brahmic scripts (Gurmukhi, Kannada, Malayalam, Oriya, Telugu, and the rest of the family) are not yet supported.
• Khmer’s own coeng/subjoined-consonant shaping uses a separate, older shaping model from the Universal Shaping Engine above (the two share only their raw Indic_Syllabic_Category/Indic_Positional_Category input data), since Khmer’s own syllable grammar and reorder rules are script-specific rather than a member of the Devanagari-family USE grammar. A coeng (U+17D2) marks the consonant after it as subjoined: a coeng+RO pair is repositioned before the syllable’s base consonant and takes the font’s pref (pre-base forms) feature, while a coeng+any-other-consonant pair stays in logical order and takes blwf (below-base forms); a pre-base dependent vowel sign is likewise moved to the syllable’s own start. The font’s default glyph pre-processing (locl/ccmp) and remaining basic features (abvf/pstf) apply globally, followed by its presentation features (pres/abvs/blws/psts). A handful of Khmer vowel signs that HarfBuzz’s own reference shaper decomposes into two glyphs at normalization time (U+17BE, U+17BF, U+17C0, U+17C4, U+17C5) are not decomposed here — a font that expects the decomposed pair rather than its own precomposed glyph for one of these five signs renders it as that glyph directly instead.
• Arabic-family joining and Devanagari USE shaping (not yet Bengali/Gujarati/Tamil/Khmer) also apply to SVG <text>/<tspan> content, resolved over each <text> element’s own flattened character stream the same way — a maximal run of mutually-joining or same-syllable-participating characters (sharing one element, zero letter-spacing, and no explicit per-character x/y/dx/dy/rotate on any but the run’s own first character — see Text) shapes and, for a right-to-left run, display-reverses as one atomic unit, matching HTML’s own per-word treatment. Not supported for <textPath> (glyphs there are still isolated nominal forms, positioned individually along the path) or under a vertical writing-mode (Arabic and Devanagari are never vertically typeset in practice).
• Bidirectional text implements the full Unicode Bidirectional Algorithm: paragraph/embedding level resolution (including the dir="auto" first-strong-character heuristic and <bdi>’s isolation), per-character reordering of mixed-direction runs within a line (not just whole-word reordering), correct placement of neutral/weak runs (digits, punctuation) against their strong-direction neighbors, and mirroring of paired characters (parentheses, brackets, etc.) in a right-to-left run. This applies uniformly to HTML text layout, inline and standalone SVG <text>/<tspan>, and @page margin-box content (headers/footers, counters, named strings).

SVG <text>/<tspan>/<textPath> request the same GSUB/GPOS features HTML text does — font-variant-ligatures/-caps/-numeric/-east-asian, font-feature-settings, font-kerning-gated GPOS kerning, and per-language LangSys selection (the bullet above, resolved from an element’s own lang/xml:lang attribute or its nearest ancestor’s — including an inline <svg>’s surrounding HTML document, when nothing in the SVG’s own tree sets one) are all supported per-element (see Text for the full property list and this feature’s own known simplifications, e.g. no small-caps synthesis fallback). <text>/<tspan> additionally get real Arabic-family joining and Devanagari USE reordering, per the bullets above.

hyphens: auto language coverage

auto performs real pattern-based automatic hyphenation only when the text’s language is known: PeachPDF resolves each element’s own language per the HTML “language of a node” algorithm — its own lang attribute if set, else its nearest ancestor’s, else <html lang="...">, else a calling application’s PdfGenerateConfig.DefaultLanguage fallback for documents that declare no language at all. With no language available from any source, auto behaves like manual (no algorithmic hyphenation) rather than guessing. A declared language resolves to the closest available pattern set — the tag itself, then progressively shorter subtag prefixes (e.g. de-AT falls back to de’s default variant, de-1996) — and a language with no match anywhere in that chain silently falls back to the same no-op rather than erroring.

auto is also a no-op on a host with no working Brotli decoder, because the pattern data is Brotli-compressed — text lays out unhyphenated rather than the render failing. This affects only a host where System.IO.Compression.BrotliStream itself doesn’t work (WebAssembly in a browser, at the time of writing) and that hasn’t registered a decoder of its own with PeachDrawing.Text.Compression.BrotliDecompression.SetDecompressor; see PeachDrawing.Text for that seam and the ready-made PeachDrawing.Text.Brotli decoder for it.

Each language’s pattern data carries its own minimum characters before/after a break (2/3 by default, TeX’s own values, when a pattern file doesn’t state otherwise); hyphenate-limit-chars layers on top of — not instead of — those, and an auto component in hyphenate-limit-chars leaves the pattern’s own minimum as the only constraint on that side.

Pattern data is sourced from CTAN’s hyph-utf8 package (see tools/Update-HyphenationPatterns.ps1 for the reproducible download/build pipeline). PeachPDF ships only permissively licensed pattern sets (MIT/LPPL/BSD-style/public-domain), consistent with the library’s own license — 73 languages/scripts are supported:

Afrikaans (af), Albanian (sq), Ancient Greek (grc), Assamese (as), Basque (eu), Belarusian (be), Bengali (bn), British English (en-GB), Bulgarian (bg), Catalan (ca), Chinese pinyin/Mandarin romanization (zh-Latn-pinyin), Church Slavonic (cu), Coptic (cop), Croatian (hr, via Serbo-Croatian Latin patterns), Danish (da), Dutch (nl), Esperanto (eo), Estonian (et), Finnish (fi, plus a fi-x-school school-method variant), French (fr), Friulan (fur), Galician (gl), Georgian (ka), German — traditional (de-1901), reformed/modern (de-1996, the default for bare de), and Swiss traditional (de-ch-1901, the default for de-CH), Gujarati (gu), Hindi (hi), American English (en-US, the default for bare en), Icelandic (is), Interlingua (ia), Irish (ga), Italian (it), Kannada (kn), Kazakh (kk), Kurmanji/Northern Kurdish (kmr, also the default for bare ku), Latin — modern/medieval (la), classical (la-x-classic), and liturgical (la-x-liturgic) variants, Lithuanian (lt), Malayalam (ml), Marathi (mr), Modern Greek — monotonic (el-monoton, the default for bare el) and polytonic (el-polyton), Mongolian, Cyrillic script (mn-Cyrl, the default for bare mn), Norwegian Bokmål (nb, also the default for bare no), Norwegian Nynorsk (nn), Occitan (oc), Oriya (or), Panjabi (pa), Pāli (pi), Piedmontese (pms), Polish (pl), Portuguese (pt, shared for pt-BR/pt-PT), Romansh (rm), Russian (ru), Sanskrit and Prakrit, Latin transliteration (sa), Serbo-Croatian — Cyrillic (sh-Cyrl, also the default for bare sr) and Latin (sh-Latn, also the default for bare bs) scripts, Slovak (sk), Slovenian (sl), Spanish (es), Swedish (sv), Tamil (ta), Telugu (te), Thai (th), Turkish (tr), Turkmen (tk), Ukrainian (uk), Upper Sorbian (hsb), Welsh (cy), and languages written in the Ethiopic script (mul-Ethi, covering Amharic am and Tigrinya ti).

Explicitly excluded — these languages have hyphenation patterns in the upstream hyph-utf8 package, but PeachPDF does not ship them because the pattern file itself is GPL/LGPL-licensed (copyleft, stronger obligations than PeachPDF’s own license) or states no license at all. hyphens: auto is a silent no-op for these languages exactly as if no pattern data existed for them at all:

Regenerating the pattern set (tools/Update-HyphenationPatterns.ps1) re-checks each language’s license against the same permissive-only rule on every run, so a language is only ever added back automatically if upstream re-licenses it.

Display & Layout

display: contents

An element with display: contents generates no box of its own: for box generation and layout it is treated as if it had been replaced by its children and its ::before/::after (CSS Display 3 §2.5). A flex or grid container’s items are therefore the children of a contents wrapper, a <tr style="display: contents"> hands its cells to the table around it, and a <span style="display: contents"> inside a paragraph disappears from its lines. Only the box tree is affected: selectors, inheritance and the element itself still exist, so its children still inherit color, font-size, direction and the rest from it.

What follows from having no box:

• The element’s own box-model and painting properties — margin, padding, border, background, opacity, transform, position, float, overflow, width/height — have nothing to apply to.
• A ::first-letter or ::first-line on the element has no effect, and text-decoration on it does not reach its content (decorations propagate through the box tree). A ::first-letter on an ancestor block still reaches into its text.
• A counter-reset, counter-increment or counter-set on it has no effect (CSS Lists 3 §4.5), including the implicit list-item counters of a <ol style="display: contents">; its <li> children still count and get their markers, and they are numbered by the list element that owns them, so a second contents list starts again at 1. A marker hangs outside the content edge of its item, so with the list’s own indent gone it is drawn in the page margin.
• unicode-bidi on it (so a <bdi>, <bdo> or [dir] element with display: contents) does not isolate or override its content, which stays in the surrounding paragraph — unicode-bidi acts on an inline box (CSS Writing Modes 4). Its direction is still inherited by its children.
• In a table, cells whose rows are contents are wrapped in anonymous rows by the ordinary table fixup, so the cells of two consecutive <tr style="display: contents"> share one row.

What it does not lose: the element is still in the document. Its id still resolves for href="#id" links, named destinations, bookmarks and target-counter()/target-text() (at the place its content begins); a link or bookmark-level on it works; its string-set is assigned where its content begins (CSS Generated Content for Paged Media §1.1); and with tagged PDF its structure element is kept around its children’s (<ul style="display: contents"> is still an /L, a <section> a /Sect). <body style="display: contents"> still propagates its background to the page canvas, and display: contents on the root element computes to block.

Elements whose rendering CSS does not fully control compute to display: none instead (Appendix B): <br>, <wbr>, <img>, <video>, <audio>, <canvas>, <iframe>, <embed>, <object>, <meter>, <progress>, <input>, <select>, <textarea>, and inline <svg> and <math> themselves. <button>, <details>, <fieldset> and <legend> just lose their box. A ::before/::after with display: contents is laid out as inline.

<progress> and <meter>

A <progress> bar and a <meter> gauge are drawn as a rounded track with a fill, at the size browsers give them - ten ems wide and one em tall, sitting slightly below the baseline - in a PDF as on a screen. They are inline-blocks, so width, height, border, background and vertical-align style them like any other box. A progress bar fills to value out of max (default 1) in its accent-color (a blue for auto); one with no value is indeterminate and shows only the track. A meter fills to value between min and max and takes the usual traffic-light color: green when the value is in the region the optimum is in (below low, between low and high, or above high), yellow in the next region and red in the farthest. The element’s content is fallback text for a browser that cannot draw it, so it is not drawn.

Known gaps: display: contents on an element inside an inline <svg> or <math> (<g>, <tspan>, <use>, <mrow>, …) has no effect, because those renderers do not read the CSS display property.

Atomic inline-level layout is approximated, not fully atomic

An inline-block whose content fits on one line has that content flowed through the surrounding inline formatting context rather than being laid out as one opaque unit. The content is correctly inset by its own border+padding (its label sits inside the padding box, and the line reserves the full padding box height), and a non-auto width sizes it as declared (CSS 2.1 §10.3.9 uses shrink-to-fit only for width: auto): the box’s background, border and overflow clip are painted at that width whether or not its content fills it — an empty one included, which is what makes the fixed-width label column and the empty-bordered-box checkbox glyph work — and the line reserves the same width, honoring box-sizing. Percentage widths resolve against the containing block’s content width, just as they do on other boxes.

A non-auto height/min-height — including a percentage, resolved against the containing block’s own height when that is itself definite (CSS 2.1 §10.5) — sizes the box’s painted background, border and overflow clip the same way (CSS 2.1 §10.6.3): the box paints at the declared (or floored-by-min-height) height whether or not its content fills it, and the line itself reserves that same height (CSS 2.1 §10.8). The extra height grows from whichever edge the box’s vertical-align anchors — the box’s own top for top and the default baseline on a box with real content, its own bottom for bottom/text-bottom, split evenly around its own center for middle — except the one case noted in the gap below. A declared height smaller than the content’s own natural height is not shrunk to — the painted box always keeps at least its natural height, the same “never pulled back” rule a wider-than-declared width already gets.

A box whose content does not fit on one line inside it — because it declares a width narrower than its content, or because its content is wider than the containing block — is instead laid out as a genuine atomic box: it establishes its own formatting context, breaks its lines at its own measure, and takes one place on the line that holds it, with its last line’s baseline on that line’s baseline. So a narrow inline-block holding a paragraph comes out as a narrow column of wrapped text, the way a browser lays it out, rather than as text broken at the width of the block around it. Content that genuinely cannot be broken — a single long word — still overflows the box rather than widening it. A box holding block-level content (a <div> inside an inline-block) has always been laid out this way.

Two knock-on gaps remain:

• An inline-block laid out as an independent formatting context (because it holds block-level content or wraps its own inline content) moves whole to the next line when its margin box does not fit, and a declared content-box width correctly grows by its padding and border. inline-table, inline-grid, and inline-flex get the same treatment: each preflights an estimated used width (a declared, non-percentage width as-is, or otherwise its own max-content width bounded by the containing block) against what is left of the line and, if it does not fit, closes the line for it, the same way an ordinary word wraps (CSS 2.1 §9.4.2). The approximated one-line path described above is the one shape this does not yet cover: it can still discover that the box’s declared width does not fit only after flowing some of its content, rather than moving the opaque box as a unit.

Pointer Interaction

Two properties describe how a document is meant to be pointed at. A PDF page has no pointer, so what each does depends on where the document is shown:

Three more properties from the same module serve a screen host and have no effect on a plain PDF page, except as noted:

Two more serve touch hosts, and are read through HtmlDocument.GetInteractionAt(page, x, y):

The keywords that only mean something for the painted parts of an SVG shape (visiblePainted, visibleFill, visibleStroke, visible, painted, fill, stroke, all) are accepted but read as auto: a shape inside an inline <svg> is not a separate hit target.

Stacking Context

Paint order follows the CSS stacking context model. A new stacking context is established by:

• the document root
• position: relative or absolute with a z-index other than auto
• position: fixed or sticky (unconditionally, regardless of z-index)
• a flex item (a direct child of a display: flex/inline-flex container) with a z-index other than auto
• opacity less than 1
• a transform other than none on a transformable element (not a plain non-replaced display: inline box) — including one whose matrix is the identity, such as rotate(0deg), scale(1) or translateZ(0)
• a perspective other than none, on a transformable element
• mix-blend-mode other than normal
• filter other than none

Elements are painted as one self-contained, atomic unit once they establish a stacking context — for example, everything inside an opacity: 0.5 box (including any absolutely-positioned descendants) fades together as a single composited group, and a z-index-ordered element’s own descendants are ordered independently of the rest of the page.

Within one stacking context, normal-flow content paints in CSS2.1 Appendix E order: in-flow block-level descendants first, then non-positioned floats, then in-flow inline-level descendants (text and inline replaced content, e.g. an inline <img>/<object>), then positioned descendants. A plain block-level box whose entire content is inline (a wrapper <div> around nothing but an inline image, for example) is treated as belonging to the inline pass itself, since painting it is what paints that inline content. This local ordering is preserved when a float is hoisted past its immediate container as long as that container is itself positioned (position: relative/absolute/fixed/sticky), even without an explicit z-index of its own. The one remaining gap: a float whose immediate container is a plain, non-positioned wrapper (no position at all) still hoists all the way to the nearest true stacking-context ancestor instead of preserving local order, so it may not paint correctly relative to non-hoisted block/inline siblings at its original nesting level.

The following triggers from the CSS specification are not supported, since the underlying properties themselves have no effect in PeachPDF (see Unsupported CSS Features): isolation, will-change, contain.

An element that needs to escape a plain (non-stacking-context) ancestor to compete for z-order at its true enclosing stacking context — for example, a z-index-ordered element nested inside a plain position: absolute wrapper that has no z-index of its own — is still correctly clipped by every overflow: hidden ancestor on its containing block chain that it passes through along the way, including when multiple such ancestors are nested.

Flexbox

CSS Flexbox Level 1 (display: flex / inline-flex) is supported, including multi-line wrapping, all alignment properties, and auto margins on both axes. Replaced elements (<img>, inline <svg>) work as flex items, including when mixed with block-level siblings. An inline-flex container is an atomic inline: its items belong to the flex formatting context inside it and stay there, whether they are inline-level or block-level, and the box as a whole takes its place on the line it sits on.

Which children become items follows CSS Flexbox §4: every in-flow child is an item in its own right, whatever its display — an inline element, a floated child (whose float is ignored in flex/grid layout), a ::before/::after pseudo-element (including one whose content is the empty string, a common spacer idiom sized purely by its own width/height), and a table-internal display such as table-row, which is blockified rather than treated as part of a table. Only a contiguous run of child text is wrapped in one anonymous item. CSS 2.1 §9.2.1.1’s anonymous block box is a block-container rule and is not applied inside a flex container, so a flex container mixing inline-level and block-level children keeps each of them as its own item. The same applies to grid containers.

Every in-flow item is blockified, per display: inline and inline-block compute to block, inline-flex to flex, inline-grid to grid and inline-table to table, so an item’s own width/height apply whatever it was declared as. A replaced item (<img>, inline <svg>) stays the item itself and keeps its intrinsic size: in a flex row, and in a grid under the default justify-self/align-self and under start, center or end, on either axis and whether or not the row has an explicit height. It stretches across its grid area under an explicit justify-self: stretch; an explicit align-self: stretch fills the row’s height and takes its width from that height through the image’s aspect ratio, which can overflow its area unless the item has a max-width. An item with no intrinsic width (an <svg> or SVG image with a viewBox but no width/height, which has an aspect ratio only) fills its area’s width under any alignment, as browsers do. An <svg> with only one of width/height and no viewBox takes the default object size, 300x150px, in the missing axis. <iframe> and <video> (without a poster) grid items keep that default size too, and stretch only under an explicit stretch; the iframe’s 2px default border that browsers add to it is not drawn. A percentage width, min-width or max-width on a grid item resolves against its grid area, not the grid container. A display: grid / inline-grid container that is itself a flex item with width: auto is as wide as its tracks plus gaps (its max-content width, with fr tracks sized from their content and percentage tracks treated as auto), then shrinks like any flex item but never below its min-content width. A grid using repeat(auto-fill/auto-fit, …), grid-template-areas, a column grid-auto-flow or subgrid tracks still takes the flex container’s available width.

Flexbox is writing-mode-aware: flex-direction: row/row-reverse always mean “main axis = the container’s own inline axis” and column/column-reverse mean “main axis = the block axis” (CSS Flexbox 1 §3), so under vertical-rl/vertical-lr a row container’s items stack top-to-bottom (physical Y) and a column container’s items stack along the block axis (right-to-left for vertical-rl, left-to-right for vertical-lr) — the same reversal logical box-model properties already apply. justify-content: left/right fall back to start when the main axis isn’t parallel to the physical left/right axis, per spec. row-gap/column-gap selection is unaffected by writing-mode (they map to flex-direction’s own row/column identity, not the physical axis it lands on). A container’s own definite-main-size resolution stays scoped to the physical Y dimension’s aspect-ratio fallback (no equivalent width-driven fallback for a vertical-writing-mode column container, where main lands on physical X) — a narrow, deliberate boundary, not an oversight.

A container whose height is a percentage that cannot resolve — because its own containing block has no definite height — is treated as auto-height, per CSS Box Sizing 4 §5. A column container then sizes to its content and stacks its items normally; there is simply no free space for justify-content to distribute.

Grid

CSS Grid Layout (display: grid / inline-grid) is supported, including explicit and implicit track sizing, line-based placement with spans, named grid lines and grid-template-areas, auto-placement, box/content alignment (including block-axis baseline item alignment), and subgrid (CSS Grid Level 2 §9). Track sizes may be lengths, percentages, fr flexible lengths, auto, min-content/max-content, minmax(), fit-content(), repeat() — including repeat(auto-fill, …) / repeat(auto-fit, …), so the common responsive-card idiom repeat(auto-fill, minmax(200px, 1fr)) works — and a calc() (or min()/max()/clamp()) length, both on its own and inside minmax()/fit-content()/repeat(). fr tracks resolve via the standard flex-fraction algorithm (honoring minmax() floors); intrinsic tracks size to their items’ content, distinguishing min-content (the longest unbreakable word) from max-content (the full unwrapped line), and an item spanning several intrinsic tracks distributes its content contribution across them so a spanned track does not collapse to zero. Each track then grows toward its growth limit with the space the container actually has (§12.6), so a grid narrower than its own content shares what there is rather than overflowing itself; whatever is still free afterwards goes to the fr tracks, or, with none, stretches the auto ones.

The grid engine is fixed to a left-to-right, top-to-bottom writing mode — direction: rtl and vertical writing modes are not honored for track order or logical placement. The following are also not supported: named lines inside repeat() and span <name> (and a named line declared after an auto-fill/auto-fit repeat is positioned as if the repeat expanded to a single track); masonry; and inline-axis (justify-*) baseline alignment of items that span more than one column, or in a vertical writing mode. Block-axis baseline item alignment shifts items to a shared baseline and grows the row to the baseline group’s max-ascent + max-descent (CSS Box Alignment 3 §9.3), so a group with a disproportionately large descent no longer overflows the row. fr row tracks are not expanded to fill a definite container height (an auto row is, with align-content: normal | stretch), and a %-bearing calc() track resolves its percentage against 0 in a row or auto-fill-count context (as a plain percentage does there). subgrid is supported (see the row above) with the noted limitations.

Multi-column Layout

CSS Multi-column Layout (column-count/column-width/columns) is supported, and a column is a real fragmentainer in the sense CSS Fragmentation Level 3 §2 means it — “a column in multi-column layout, or a page in paged media”. The column a piece of content is in is what its break decisions are made against, so the break machinery works inside a column without being told about columns:

• break-before: column / break-after: column force a break at the column boundary, so the content after them starts the next column and the one before them is left short.
• break-inside: avoid (and avoid-column) keeps a box off a column boundary, moving it whole to the next column.
• break-after: avoid / break-before: avoid (and avoid-column) keep a heading with the content it introduces at a column boundary, so a heading is not left at the foot of the column the content it belongs to has moved out of.
• break-before: page (and the four directional values) forces a break to the next page, not the next column: none of a container’s columns is on another page.
• Monolithic content — a replaced element or a scroll container (inside a column container every scroll container qualifies) — moves whole to the next column rather than being cut by the boundary.
• orphans and margin truncation apply at a column boundary the same way they apply at a page boundary (widows, which is enforced after the fact by re-running the pass that filled a fragmentainer, is a page-context rule only).
• A container whose content outlasts its columns continues on the next page, resuming where its last column stopped rather than starting over, and balances the fragment that holds the end of the flow.
• A child continues into the next column rather than moving to it whole: a paragraph’s first lines stay in one column and the rest flow into the next, each fragment carrying its own background, border and padding.
• The break need not fall between two of the container’s own children. A block nested any distance below one is split at the column boundary too, and the content after the break starts the next column flush at that column’s top, inside the continuing block’s own fragment there. The continuing block’s top border and padding are re-opened above it only under box-decoration-break: clone; under slice the box is cut at the break and nothing is inserted there — and this holds however deep the nesting goes, so a continuing block’s own fragment begins where its content does. The multi-column container’s own border and padding are not re-opened at a column boundary, since a container is not fragmented by its own columns. See Decorations at a break.

column-fill: balance (the default) aims for equal-height columns, and column-fill: auto fills each column before starting the next.

Column breaks. The break values that name the column fragmentation context — column on break-before/break-after, and avoid-column on break-inside — apply inside a multi-column container and nowhere else, which is what §3.1 means by naming a context. Outside one there is no column boundary for them to speak about, and they are ignored rather than being treated as their page-context equivalents.

Each value covers exactly the context it names, and avoid covers both:

A forced column break carries the same propagation rule a forced page break does: declared on a container’s first in-flow child it is the break point before the container, so the container starts the next column along with the element. And an avoid that cannot be satisfied is relaxed rather than obeyed pointlessly — a box too tall for a whole column is split, since moving it to the next one would leave it splitting there instead.

Keep-with-next at a column boundary. The keep-with-next chain works at a column boundary as it does at a page one, with avoid and avoid-column naming the column context (and avoid-page naming only the page). Since the UA default stylesheet applies h1-h6 { break-after: avoid }, a heading inside a multi-column container is kept with the content below it out of the box: where that content starts the next column, the heading starts it too. §4.3’s relaxation applies as it does on the page grid — a run too tall to fit the destination column alongside the content it is chained to is trimmed from its front, so the subheading immediately above travels even where the chapter heading above that cannot.

Two details follow from a column having no lower coordinate to move a run to. The break is stated before the head of the run and the next column lays the whole run out there, rather than the members being shifted; and the head has to be a box the column being filled actually placed — a run reaching back into a column that is already filled, or one whose head is the very box this column began with, is left where it is, since starting the next column at the same place would put the identical question to it again.

The chain applies where the content is moved whole by the column boundary. A box that asks not to be broken by one (break-inside: avoid-column) moves alone: it has begun splitting, so its full height is not yet known, and §4.3 gives a constraint up rather than acting on one it cannot show to be satisfiable — moving a heading into a column of its own while the content it introduces breaks again in the next is worse than leaving it. column-fill: balance also rarely leaves room for the pull, since a balanced column’s height is derived from the content it holds; a page-bounded column (column-fill: auto, or a container taller than its page) is where a heading and its content travel together.

A forced page break escapes the container. break-before: page (and left/right/recto/verso) inside a multi-column container starts the next page: it names the page grid, and none of the container’s columns is on another page. The columns it has opened so far end there, the content after the break opens the page the break names, and the container continues in its columns on that page. A directional value reaches the side it asks for here, exactly as it does outside a container (Directional page breaks) — but the page it skips to get there is not materialized: outside a container that skipped page is emitted as a real blank page, and inside one it is dropped, so the document is a page shorter than the same break would produce elsewhere. column-fill: balance balances the columns before the break over the content that precedes it, since the break is where this fragment’s flow ends.

The above holds regardless of how deep inside the container the forced break is declared — on the container’s own child or on a descendant further down a wrapper’s subtree.

A column is at least as tall as its unbreakable content. A child a multi-column container cannot fragment — a <table>, or another layout engine’s container — is placed in one column whole, and where it is taller than the height balancing chose, the column it lands in grows to hold it rather than the overflow being clipped away. A <table> nested in a multi-column container therefore renders in full.

A floated child of a multi-column container is positioned within the column it appears in, and the container’s automatic height grows to contain its floats. A float wider than its column overflows it rather than being narrowed. A container holding only floats lays them out in its first column. Text beside a float is divided into columns like any other text: the float sits in the column where it appears and shortens the lines beside it. A float placed after text on the same line moves that text beside it when the line has room for both, and otherwise starts the next line. A block-level float whose margin box does not fit below the content already in its column moves to the top of the next column, while the in-flow content after it keeps filling the column it was in; a float taller than a column, or the first thing in one, stays. Two limitations: a float written among inline content that does not fit stays in its column and overflows it, and column balancing does not count the space a float takes before it is moved. A multi-column scroll container (overflow other than visible) with a height or max-height that holds only text is laid out as one inline flow, not in columns, and so is a multi-column container that holds a float inside a table cell.

• A box split at a column boundary leaves that edge open, per box-decoration-break: slice — no border is drawn where the break is, only where the box really starts and ends. See Decorations at a break.

• A decoration defined over the whole box — a border-radius, a gradient or image background layer, a box-shadow — is measured against the whole box under slice, so a rounded, gradient-filled box divided between two columns rounds only at its true ends and its gradient runs on from one column into the next. See Decorations at a break.

A multi-column container nested inside another one splits its own children per inner column, independently in each outer column it is filled in.

Positioning

Used with position: relative, absolute, or fixed.

An absolutely (or fixed) positioned box is blockified (CSS Display 3 §2.7 / CSS 2.1 §9.7): an inline-level computed display (inline, inline-block, inline-flex, inline-table) is coerced to its block-level equivalent, so e.g. a ::before with no explicit display still becomes a real out-of-flow block. An absolute box’s containing block is the padding box of the nearest positioned ancestor (CSS 2.1 §10.1), which is what percentage width/height/top/left resolve against (not the nearest in-flow block container, when those differ); a fixed box’s is the page area of the page it is drawn on, so its offsets and percentages are measured from that page’s content corner and can differ from page to page when the pages do. With width: auto and both left and right set, the box fills the space between them (§10.3.7); likewise height: auto with both top and bottom set (§10.6.4). When top, height and bottom are all set instead, an auto block-axis margin absorbs whatever space is left over — one auto margin takes all of it, and margin-top: auto with margin-bottom: auto splits it evenly, which is the usual way to centre an absolute or fixed box vertically. Content-sized containing blocks use their final height for this calculation. A negative margin on the opposite edge is honored the same way, so a box can be pushed entirely past its containing block’s edge. Out-of-flow children of a flex or table container are laid out too (they don’t participate in flex/table layout but still get positioned and sized). An absolute box is drawn on the page its offsets place it on, even when that page comes before the one its source position falls on: with no positioned ancestor its containing block is the first page’s area, so top: 5pt puts it at the top of page 1 wherever it appears in the document. It takes no part in placing the boxes around it, so the content after it in the same block starts where it would without it. An absolutely positioned box taller than the page breaks between its lines and adds the pages it needs, as a browser prints it, and the content around it is not affected by where it breaks.

An absolutely positioned box inside inline content, such as a badge in a <span> in the middle of a sentence, stays out of the line. The text before and after it stays on the same line, and the inline around it is not split (as it would be around an in-flow block). An absolutely positioned box contributes nothing to the shrink-to-fit width of a float, table cell or flex item around it, nor to a table cell’s content height, so a badge hanging below a cell’s text does not move that text. When the nearest positioned ancestor is an inline element, such as a <span style="position: relative">, that inline is the containing block. For an inline on one line, CSS 2.1 §10.1 defines it as the box around the inline’s padding edges. For an inline that wraps, PeachPDF takes each edge from the line fragment CSS Positioned Layout 3 assigns it to, and measures it at that fragment’s padding edge as Chromium does (that specification names the content edge): the top and left edges come from the inline’s first line fragment, and the bottom and right edges from its last fragment; in rtl text, left and right come from the last and first fragments instead. So top: 0; left: 0 sits at the start of a highlighted word, and bottom: 100% puts a label just above it. An inline that holds nothing but the positioned box, such as an icon or tooltip wrapper, is a zero-width box at its place in the line, one line of its font tall, and the positioned box is placed from there.

Known limitations:

• Static position is used in block flow and among inline content. An absolutely positioned box whose offsets on an axis are both auto sits where it would have been in the normal flow on that axis (CSS 2.1 §10.3.7): at its parent’s content edge across and below the previous in-flow sibling down; a box written among inline content sits at its place on the line (right after the preceding word, at the line’s top), carried through text-align and bidi reordering. In a direction: rtl parent the box’s right margin edge sits at the static position (the parent’s content right edge, or the place on the line). In a table cell with vertical-align: middle or bottom, such a box moves with the cell’s aligned content.
• A positioned inline that a page break falls inside forms its containing block from the fragments placed so far. An absolutely positioned box in such an inline resolves bottom and right against the last fragment on the page the box is laid out on, rather than against the inline’s true last fragment on a later page. top and left are unaffected, and so is an inline that does not cross a page break.
• An empty positioned inline between runs of opposite direction is placed at the far end of one run. In mixed-direction text, such as an rtl paragraph with an English phrase, a zero-width inline at the boundary between the two directions goes to the far end of the neighbouring run instead of sitting between them. Within a run of one direction it is placed correctly.

Lists

Page Breaks

These properties control how content breaks across PDF pages. Both the legacy page-break-* names and the modern break-* names are recognized.

Break values with no layout effect. PeachPDF accepts the complete CSS Fragmentation Level 3 §3 value set on every break property, so a stylesheet written for a browser parses unchanged and its other declarations are unaffected. The values that change the output are page, left, right, recto and verso on break-before/break-after (forced page breaks — see Directional page breaks below), and avoid and avoid-page on break-before/break-after (keep-with-next, below) and on break-inside. column and avoid-column are honored inside a multi-column container, which is the only place a column boundary exists (Column breaks, below). The remainder are completely inert — not a weaker version of the behavior they name, but no effect at all: region and avoid-region are permanently inert, since PeachPDF has no CSS Regions fragmentation context for them to break into, and column/avoid-column say nothing about a document with no multi-column container in it. A value naming one context deliberately does not fall back to bare avoid or to page in another: a hint about column or region breaks must not change pagination, and a request for a column break must not become a page break. All of these are stored and cascade normally.

Directional page breaks (left, right, recto, verso). Per CSS Fragmentation Level 3 §3.1 these force one or two page breaks, so that the content following the break begins on a page of the requested side. Pages alternate right, left, right, … from the first page — the same left-to-right progression @page :left / @page :right select on — so a break-before: right whose content would otherwise land on a left page inserts one blank page ahead of it. recto and verso are right and left in this progression.

A page inserted this way is an ordinary page: it takes its @page context’s canvas background and margin boxes, and it counts toward counter(page) and counter(pages). @page :blank (MDN) selects exactly these inserted pages, so @page :blank { @top-center { content: none } } suppresses the running header on them while the surrounding pages keep theirs. It matches only a page a directional break inserted, never one that is merely empty or one a plain break-before: page opened.

Two limitations. Where a document also uses per-page @page left/right margin overrides, which re-wrap each page’s content to its own width, the page a break lands on (and therefore whether a blank page is needed) depends on that re-wrapping, which is resolved iteratively rather than exactly.

And the side is resolved against the page’s position in the full page grid, while the printed page number counts only the pages actually produced. Those agree for an ordinary document, but they drift apart after a page that was dropped for having no content on it — most plausibly a tall empty gap between two blocks. Past such a gap, a break-before: right can land on a page that prints as an even number, and @page :right will not style it. Keep large vertical gaps out of a document that relies on which side its pages fall on.

Keep-with-next (break-after: avoid / break-before: avoid). Per CSS Fragmentation §3.1, an avoid (or avoid-page) on either side of a sibling break point forbids an unforced break between the two boxes. PeachPDF honors this wherever it relocates content to the next page: when a box is relocated wholesale (a table whose body would cross a page boundary, a break-inside: avoid box, an orphans/widows push) or when ordinary word flow pushes a block’s first line to the next page, the maximal run of preceding siblings chained to it by avoid values goes with it, so a heading is never stranded at the bottom of the page its content just left. The run is laid out again at its destination rather than shifted there, so each of its members reads as though it had started on that page — including where the heading was placed on an earlier page than the one the decision is taken on, which is the ordinary case whenever the content’s own text breaks across the boundary: the page that placed the heading is laid out again too, and the fragments it had already produced are withdrawn. The UA default stylesheet applies h1-h6 { break-after: avoid } (under @media print, which PeachPDF always uses), so headings get this behavior out of the box. Chains are transitive (e.g. h2 + h3 + paragraph move as a group), a forced break value on either side of a pair takes precedence over avoid per §5.2, and an avoid that cannot be satisfied in full is relaxed progressively per §4.3 rather than abandoned: the run is trimmed from its front until what remains fits the destination — the subheading immediately above the content travels even where the chapter heading above it cannot — and only where no member can travel does the content move alone, exactly as it would without the avoid. Two shapes keep the older behavior of moving the group rather than laying it out again — a run whose members include a table that repeats a header, which does not survive a second layout, and a heading on a page that no single layout pass was filling (a forced break can step over a page without ending the pass). The heading still travels with its content in both; only the way it gets there differs, and the paragraph below it can then show a little extra space where the page boundary fell inside it. The run is found at the break point the content really names, so a heading is chained to it whether it is a sibling of the moving box or of a container that box begins (see break propagation above). The same chain applies at a column boundary, where avoid-column joins avoid in naming it — see Keep-with-next at a column boundary — and between two flex lines or grid rows, where the chain runs over lines rather than siblings — see Breaks in flex and grid containers.

Margin truncation at page breaks: per CSS Fragmentation Level 3 §5.2, when a vertical margin between two elements is large enough that it alone would push the following element onto a later page (an unforced break — no explicit break-before/break-after/page involved), that margin is discarded entirely and the following element starts flush at the top of the very next page, rather than the margin paginating through as literal blank pages. A margin-top large enough to visually separate content across a deliberate page boundary should use an explicit break-before: page (or page-break-before: always) instead — margins after a forced break are preserved, not truncated, per the same spec section. This applies to normal block flow, including inside a multi-column container, whose columns are fragmentainers; flex, grid and table position their own children and are not covered.

The element need not have a preceding sibling: the break point before a container’s first in-flow child is a real break point too, and its margin is truncated at one. This holds when something on the container — a border or padding — keeps that margin from collapsing out of the child and into the container. Where nothing does, the margin collapses all the way up the ancestor chain and belongs to the outermost box it reaches rather than to the child, and a margin that reaches the root that way still paginates as blank space.

Forced breaks before a first child, and break propagation. break-before (and the legacy page-break-before) is honored on a container’s first in-flow child, which is the common section > h1 { break-before: recto } idiom. Per §3.1 the break point before a first in-flow child is the break point before its container, and likewise a break-after on a last in-flow child is the break point after the container — so the value travels outward through every box the element begins or ends, and the outermost such container is what takes the break and moves with it. Its own background, border, padding and margin therefore begin the new page along with the element, rather than being left spanning the boundary with an empty copy on the page the content left. A heading chained to the moved content by break-after: avoid is carried along too, whether it is a sibling of the element or of the container, so the two shapes behave the same way.

Propagation stops before the fragmentation context itself, and before any box whose children are positioned by a layout engine of their own — a flex or grid item, a table cell, a multi-column child. A break declared on the very first thing in a document therefore has nothing before it to break from: no break is taken and no blank page is manufactured in front of it, which is §4.4’s “no empty fragmentainer” rule. For the same reason, a forced break that is not taken still counts as one for margin purposes: there is no break point in front of such a box for a margin to adjoin, so its margin is preserved rather than truncated.

Combining break values at one break point. Where more than one forced value applies at a single break point — this box’s break-before, the preceding box’s break-after, and anything either of them propagates outward — §3.1 asks that all of them be honored. A directional value forces a page break as well as naming a side, so it subsumes a plain page. Two conflicting directional values cannot both be honored, and there the spec is explicit: the value on the latest element in flow wins, which for a value travelling outward is the deeper one.

The same applies to the breaks that are decided after content has been placed rather than declared in advance — break-inside: avoid, monolithic content, and an orphans push. When one of those relocates a container’s first child, the container goes with it, so its border, background and padding open the new page rather than being cut in two. The exception is a container too tall for the destination page: moving it there would leave it not fitting either, so it stays and only the element moves — the same progressive relaxation an unsatisfiable avoid gets.

Breaks in flex and grid containers. A flex container’s break points are between its lines, and a grid container’s between its rows (CSS Fragmentation Level 3 §3.1) — not between the items sharing one, which the cross-axis alignment holds together. So break-before on an item, and break-inside: avoid (or avoid-page) or monolithic content among its items, move the whole line or row to the next page rather than the item that asked. An item spanning several grid rows travels with the first of them.

A forced break is taken from either side of the break point, as §3.1 requires: break-after: page (or the legacy page-break-after: always) on an item starts the line or row after it on the next page, exactly as break-before on that following line’s own items would. A directional value (left, right, recto, verso) is honored in full here, as it is in block flow: the line or row opens a page of the requested side, and a blank page is inserted where the side needs one — see Directional page breaks. Where more than one value applies at one break point they combine by §3.1’s rule, so a directional value on either side subsumes a plain page on the other. The line that declared the break-after stays where the flow put it — the break is after it. A break-after on the last line or row names the break point after the container itself, which a flex or grid container does not act on: a break travelling out of an item would name a position the engine is about to overwrite. An item spanning several grid rows is the earlier sibling of the row after the last row it covers, so its break-after is taken there rather than at a boundary running through the middle of the item.

A forced break at a point that already is a page boundary is already satisfied, per §4.4’s “no empty fragmentainer”: a line whose top is flush on a page’s content top stays there rather than being moved a further page on. A directional value asks for more than a boundary, though — it asks that the content begin on a page of the named side — so a flush line satisfies it only where the page it already begins is that side, and otherwise still moves.

Keep-with-next between two lines or rows. break-after: avoid (or avoid-page) on one line’s items, and break-before: avoid on the next line’s, both forbid an unforced break at the point between them, and PeachPDF honors it by moving the earlier line: where a page boundary would otherwise fall there — because the later line was relocated, or simply because the flow put it on the next page — the earlier line travels with it, so a heading that is a flex item is not stranded at the foot of the page its section body just left. The UA default stylesheet’s h1-h6 { break-after: avoid } makes this the ordinary case. Chains are transitive over consecutive lines, a forced break at the same point takes precedence per §3.1, and an avoid that cannot be satisfied is relaxed progressively per §4.3 rather than abandoned: the chain is trimmed from its front until what travels fits the destination page, and a chain reaching the top of its own page is dropped altogether, since moving all of it would leave that page blank and ask the same question again on the next one.

An item with no break value of its own is left where it is, and the page boundary cuts it — the same answer ordinary block content gets when it has no line to break at. A line or row taller than a whole page is also left alone, since moving it could not help.

Which line is above the boundary is a question about the page, not about the source. The two orders agree in a grid and in a flex container that wraps the ordinary way, but flex-wrap: wrap-reverse puts the first line in the source last down the page. PeachPDF reads such a container down the page: the lines that follow one that moves are the lines physically below it — there, the earlier ones in the source — so a relocated line is never drawn over the top of one that stayed put. Identifying the break point is still §3.1’s question about source order, so break-after on the first line’s items and break-before on the second’s name the same point, which under wrap-reverse is the boundary above the first line — and it is therefore that line which opens the next page.

The break point before the container’s first in-flow child is the break point before the container itself, and that boundary sits above the container’s topmost content whichever line happens to be there — so under wrap-reverse a break-before on the first item still starts the whole container on a new page, rather than tearing off the one line that sits at the bottom.

A column container — flex-direction: column or column-reverse, wrapping or not — stacks its lines along the inline axis instead: two side-by-side lines sit in one range down the page, so no page boundary falls between them and a break value declared at that point has nothing to act on (unchanged from before). What such a container’s lines do have are real break points between the items within one line, since those are genuinely stacked in the block axis — exactly the shape a row container has between its lines, one level down. So break-before/break-after between two items of the same column line is honored (taken from either side, per §3.1), and break-inside: avoid or monolithic content on one item moves only that item — and whatever follows it in the same line’s block-axis order — rather than the line’s earlier items or any other line. Only the container’s own first in-flow child still speaks for the boundary above the container itself: every other line’s own leading item starts at that same block-axis position with nothing genuinely before it in flow order, so a break value declared there is inert, the same way the point between two side-by-side lines is. Two side-by-side lines are independent of each other for this purpose: moving an item in one because of its own break value never displaces the other line, which is exactly what “no break point between lines” already implied.

Two limits are worth knowing. A flex or grid container inside a table is positioned against the table’s own row grid, so its lines are left to the table engine rather than moved against the page grid. And an inline-flex or inline-grid box is an atomic inline — where it sits is the line it is on to decide.

Item content fragments across pages for every flex and grid shape: a flex-direction: row/row-reverse line’s items (whether the container has one line or wraps into several), a flex-direction: column/column-reverse line’s items (walked in sequence — see below), and every grid row’s items (including a row-spanning item’s own content, and a subgrid item’s). Each item’s own content — a line of text, or a nested block-level layout such as a column-count/column-width container — continues on the next page rather than being moved whole or cut when it does not fit. This composes with everything above: the whole-line/row relocation described earlier in this section still decides which page a line or row begins on, and each item’s own content is then laid out for real once it is there.

A row/row-reverse line’s items are css-break-3 §2.1 “parallel flows” (the spec’s own example is exactly this shape) — they commit together, one item’s own content stopping partway through a page does not stop a line-mate beside it from continuing or finishing on its own. Grid rows read the same way. A column/column-reverse line’s items are instead a sequential flow along the block axis: each is walked and committed in turn, so a later item’s content continues onto the next page only once an earlier item has finished; a flex-wrap column container’s several lines, which sit side by side sharing no block-axis range, each run this sequence independently of the others. This composes with the break-value behavior described above: a forced break-before/break-after between two items of one line, or a break-inside: avoid item that straddles a boundary, decides which page each item begins on, and each item’s own content then fragments across pages from there exactly as it does anywhere else in a column line.

A line or item content taller than the page’s whole content band is left alone wherever it appears, the same monolithic content answer ordinary block flow gets, since there is no page that could hold it — moving it could only repeat the same overflow on the next page. It is clipped to the page it begins on rather than continued: give such content a break-inside: avoid (or size it so a line cannot straddle) where that would be unacceptable.

Breaks between table rows. The break point between two rows of a table is an ordinary break point (CSS Fragmentation Level 3 §3.1), and a forced value declared there is honored: break-before: page (or one of the directional values) on a <tr> starts that row on the next page even where it would have fitted, and a break-after on the row above it does the same. A value on a <tbody>, <thead> or <tfoot> is a value at the break point before its first row or after its last, so it is honored at that row. A table repeating a header carries the header onto the page such a break opens, exactly as it does at a break the row heights themselves forced.

A row that would straddle a boundary is carried onto the next page whole rather than split, wherever the engine can move it. A row whose cells wrap over several lines is otherwise split between those lines at the page foot, as a block is; break-inside: avoid (or page-break-inside: avoid) on the row, or on one of its cells, carries it onto the next page whole instead. A row that is the first on its page, or is taller than a page, is still split there, and so is a row of a table nested inside another table’s cell. Inside a multi-column container, break-inside: avoid on a row does not carry it into the next column.

A cell whose rowspan crosses a page break is split at the break. CSS Tables Level 3 asks for a row to be kept unfragmented only “if the cells spanning the row do not span any subsequent row”, so the row that ends a span is carried onto the next page whole like any other row, while the spanning cell itself is fragmented: its box closes at the foot of the page it began on and opens again at the head of the next, its borders and background running the depth of each fragment, and — as the spec requires — no border is drawn at the break on either side of it. The column-context values (column, avoid-column) name a fragmentation context a table does not establish; inside a multi-column container they are the container’s to act on.

This holds even where the spanning cell’s own content is taller than the page it began on: the cell’s content stops and resumes across pages the same way any other content does, and the cell’s box closes and reopens with it rather than being stretched across every page in between.

Limitation: a spanning cell is not split inside a multi-column container, where a table’s rows are left to the table’s own grid rather than moved against the column; and the cell’s vertical-align resolves against the fragment on the page it began on rather than against the whole cell, so middle centres its content in that fragment.

A row taller than the page is left where it is, and the rows after it continue below it. Where a row’s cell holds a block taller than the whole content band — a fixed-height figure or chart, say — there is no page that could hold that row, so it stays where it is and overflows across as many pages as it needs (CSS Fragmentation Level 3 §4.3: moving it could only recreate the straddle). The rows after it are placed immediately below where it ends, on the page its bottom actually landed on.

A repeating header is carried onto every page the table spans, and the row resumes below it. CSS Tables Level 3 repeats a <thead>/<tfoot> on each page a table spans, not on each page it broke on, and asks the user agent to “leave room” for the group there. A page that a too-tall row merely overflows through is one of those pages — and the only way to leave room on a page nothing breaks on is to slice the row itself, which CSS Fragmentation Level 3 §4.3 allows in as many words: “the UA may also fragment the contents of monolithic elements by slicing the element’s graphical representation”.

So the row is neither resized nor moved. Each page draws it from a different origin and shows the strip belonging to that page, and the strips meet exactly — a background, a gradient or an image runs continuously from one page to the next, picking up below the repeated header rather than underneath it. This applies to a block taller than the page, to a replaced element such as an <img> or an inline <svg>, and to the second and later pages of a single-row table taller than one page. A <tfoot> closes each of those pages the same way, from the other end of the band.

Limitation: the room is left on the pages a row overflows through, which are the pages no move could help with. A row that would fit the next page is moved there whole instead, as before, and a table that did not fragment at all is moved whole by the rule below — neither is sliced. Where a page’s own band is short enough that the repeated groups would leave the row no room at all, that page gives the row the whole band, since a page that took no content could never finish the document — the repeated group is still drawn there, so on that page alone it overlaps the row rather than sitting above it. Reachable only under per-page @page geometry, since the quarter-of-the-page conditions above otherwise keep both groups well inside a band.

A table that did not break moves whole. A table breaks between two of its rows when the next row does not fit, and where no row break was taken at all — most often a single-row table, or one whose only row is taller than the page — the table did not fragment, and it is carried onto the next page in one piece rather than painting sliced across the boundary. This applies to every table, including one repeating a <thead> or a <tfoot>: the header follows it onto the page it lands on. A table taller than one page is left where it is, since moving it would only recreate the straddle. A heading chained to the table by break-after: avoid — the user-agent print default for h1–h6 — travels with it, as at every other relocation.

A cell’s text breaks between lines, not through one. Where a cell holds more text than the page has room for, the text continues on the next page and each line lands whole on one page or the other — a line is never cut through the middle and drawn on both. This holds for the cell’s own text and for text inside a block within it alike.

A row whose cell runs out of room continues on the next page. A table is fragmented like any other content: where a cell cannot fit the rest of its content on the page, the row it is in continues on the next one, and the rows after it are placed there rather than being left unplaced. The cells of one row are fragmented independently (CSS Fragmentation Level 3 §2.1, css-tables-3 §6.1): a short cell beside a long one finishes on the first page and none of its content is drawn again on the continuation, while the long one picks up exactly where it stopped. A table repeating a <thead> carries it onto every page such a row reaches, and room is left for it there, so the continuing cell resumes beneath the repeated header rather than being overlapped by it — the same as at a break between two rows. A repeating <tfoot> closes each of those pages the same way, read from the other end of the band: CSS Tables Level 3 asks for room to be left for a repeated header and says “the same applies for footer rows and the table bottom border”, so the continuing cell’s own text stops above the repeated footer rather than running underneath it. The footer on the table’s last page is a different footer — the one that closes the table, under its final row.

Limitation: the room left for a repeated <tfoot> is left for the cell’s own text. Content in a cell that runs its own fragmentation — a multi-column container — and a block inside a cell that is moved whole rather than split are both placed against the full page instead, so either can end up underneath the repeated footer.

A finished cell’s box continues with its row. §6.1 continues the row’s box into the next page and every cell’s box with it, so the cell that finished is drawn there as its own background and borders running the full depth of the row’s continuing fragment, with no content in them — which is what a browser draws. That depth is set by the cells that do continue into the page, since a cell with nothing left to place asks for no height of its own. The edges the page break itself made carry no border, because box-decoration-break defaults to slice: the cell closes with a border at its real top and its real bottom only, exactly as a block spanning pages does.

When a <thead> or <tfoot> repeats. CSS Tables Level 3 makes repetition conditional, and PeachPDF applies both conditions:

• The group must carry an avoiding break-inside. The user-agent stylesheet supplies thead, tfoot { break-inside: avoid } under @media print (which PeachPDF always uses), so this is what every table gets by default — repetition out of the box, as in a browser. Writing break-inside: auto (or break-inside: avoid-column, which names a context a table does not establish) on the group is the way to opt out: the group is then laid out once, in flow, at the table’s top or under its last row, and the pages after the first are given wholly to the rows.
• The group must be shorter than a quarter of the page — a quarter each for the header and the footer, per the spec’s “up to one quarter for header rows, and up to one quarter for footer rows”. A taller group is laid out once instead. The room a repeated group takes is genuinely reserved on every page the table spans (see above), so without the cap a tall group is charged its own height out of every one of them — and a group taller than the page’s content band would leave no page able to make progress at all. The quarter is measured against the whole page box, margins included, which is what “the page height” means here — not against the smaller content band the group is actually drawn in.

Both are decided once per table, and a page a row continues onto inherits that decision rather than re-taking it. A table laid out with no page grid at all — a measurement pass, or an unpaginated container — has no page to take a quarter of, so only the break-inside condition applies there.

A group that is not repeated still has to fit the page it is drawn on. No room is reserved for it — reserving room on every page is exactly what not repeating avoids — so where the last row runs to the foot of its page, the closing <tfoot> is carried onto the next one whole rather than drawn across the boundary. It moves as a unit, since a row group cannot be split; a footer taller than a whole page is left where it is, because moving it could only recreate the straddle.

Two limits. Keep-with-next (break-after: avoid) between two rows is not honored — the chain is read among block-flow siblings, and a table’s rows are placed by the table itself. And a break value on a box inside a cell is likewise the table’s row grid to answer, not the page grid’s.

Monolithic content moves whole rather than being split (CSS Fragmentation Level 3 §4.1). Content treated as unbreakable is carried onto the next page in one piece where it would straddle a page boundary. Two kinds qualify:

• Replaced elements — <img>, <svg>, <iframe>, and an <object>/<video> whose resource resolved to an image. These have no inner structure to fragment.
• Scroll containers — a box whose overflow is not visible or clip and that has a definite logical height. A percentage height against an indefinite containing block is automatic for this purpose, and in vertical writing the logical height is the physical width. A scroll container with an automatic height can break between lines and blocks — with a max-height too, for as long as its content is under the cap — so a long code listing can begin in the space remaining below its heading, and an overflow: hidden wrapper around the page body does not slice a line at the page edge; a min-height alone does not make it unbreakable, and break-inside: avoid keeps a short one together. The root element is excluded, because its overflow propagates to the viewport rather than making it a scroll container (CSS Overflow Level 3 §3.3); a paginated document has no viewport for it to propagate to, so the common html { overflow: hidden } idiom does not declare a whole document unbreakable. <body> is excluded on the same grounds, but only while the root’s own overflow is visible — once the root declares one, the body’s own overflow and sizing determine whether it is monolithic. (overflow: clip is not currently implemented and computes as visible, so it is excluded either way.)

§4.1 allows an implementation to treat an overflow: auto or scroll box as monolithic, and an overflow: hidden box only when its logical height is not auto and it has no specified maximum. PeachPDF keeps a box with a definite height unbreakable for every overflow value, and breaks one with an automatic height and a max-height like a block: between its lines, for as long as the content placed is under the cap. The cap counts the box’s consumed height across the pages it breaks over, not the distance from its first fragment, so the unused strip at a page foot is not content and the box ends on the page where its lines add up to the cap. Content past the cap (clipped away for overflow: hidden) is laid out without any break, so the content after the box is never lost and clipped lines never add a blank page. A box with a max-height that holds a table, flex or grid container stays whole instead, because those engines take breaks of their own that cannot be held back past the cap.

One boundary is worth knowing: the rule applies to normal block flow, and inside a multi-column container, whose columns are fragmentainers. A scroll container that has no size of its own and sits inside a multi-column container is nonetheless kept unbreakable, because that engine clips it per column and letting it break there dropped lines at the edge. One that is a flex or grid item breaks between its lines like any other block. Inside a flex or grid container it applies to the whole line or row the box is in — see Breaks in flex and grid containers. A monolithic box inside a table is placed against the table’s own row grid, so it can still be split.

A box that had already begun flowing its own text across the boundary is laid out again at its new position rather than moved to it, so it reads exactly as it would have if it had started there — no blank band inside it, and no unused height. The same is true of every relocation described in this section: break-inside: avoid, monolithic content, and the widows fallback below all share one mechanism. Neither of the two §5.4 line minimums relocates anything in the ordinary case: an orphans violation makes the break fall before the box (see orphans above), and a widows violation makes the fragment before the break keep fewer lines, so in both the box is laid out once, where it belongs. A scroll container taller than every page’s own content band cannot be helped by moving it, so it is not moved at all: its content simply lays out unbroken and overflows across as many pages as it needs, each page showing its own slice — the same way any other oversized content already does.

One case still moves the box instead of laying it out in place: a keep-with-next run whose heading was already settled on an earlier page — which happens when the box’s own text broke across the boundary and it finished later — moves as a group: the heading still travels with its content, but the content keeps the gap.

A line box is never split across pages (CSS Fragmentation Level 3 §4.1). When a line does not fit on the page it started on, the whole line moves to the next one — including any part of it that would have fitted.

Content continues at the page’s content edge. Where content flows onto a following page it starts at that page’s content edge, rather than fractionally below it.

Layout gives up pagination before it gives up content (CSS Fragmentation Level 3 §4.3). Every rule above may decline to place content where it would rather not go — break-inside: avoid, a keep-with-next chain, monolithic content, orphans and widows — and §4.3 asks that such constraints be given up progressively rather than at the cost of content. The last thing given up is pagination itself: if a page is reached that layout cannot get past, the rest of the document is laid out from that page on in one piece, with no further break decisions, so it runs past the page’s edge and is cut at each boundary rather than broken at one. Those pages will look wrong, but the document renders.

Decorations at a break

When a break splits a box, box-decoration-break (CSS Fragmentation Level 3 §6.2) decides whether its border, padding, background, border-radius and box-shadow belong to the box as a whole or to each piece. Both values are honored, and — as the spec requires — at every kind of break: the page breaks of a block box, the column breaks of a box in a multi-column container, and the line-box breaks of an inline box that wraps.

slice, the initial value, renders the box as though it were never broken and then cuts it at the break. So no border and no padding is inserted at the break, no shadow is drawn along a broken edge, and the background, gradient layers and corner radii follow the whole box’s geometry. A wrapping <span> with a background gradient and rounded corners therefore renders as one continuous shape whose gradient runs on across each wrap and whose only rounded corners are at its true start and end — the same as a browser.

clone wraps every piece independently: its own border on all four sides, its own padding, its own radii and shadow, and its own background, so a no-repeat background image is drawn once per piece rather than once per box. This is what to reach for when every line of a highlighted inline should be a self-contained rounded pill, or when a block crossing a page boundary should be closed off with its own border on each page. Space is reserved for the cloned border and padding, so they push the box’s content rather than overlapping it — and where boxes are nested, each piece opens inside its ancestors’ own re-opened border and padding.

Margin is cloned at a line break, alongside the border and padding, so each line of a margined inline keeps its gap on both sides. It is not cloned at a page break, because a margin adjoining one is already truncated to zero (see Margin truncation at page breaks above), leaving nothing there to clone.

Limitations:

• Room is reserved for clone’s border and padding in normal block and inline flow, and at a column break — including for a box whose own content is blocks rather than text, which is split at a column boundary like any other. Inside a flex, grid or table, whose own engine positions its children, a cloned decoration at a break is painted but no room is made for it, so it can overlap content.
• A page break is decided against the text itself rather than the line box around it, so the half of a large line-height’s leading that falls below the last line on a page is not counted. A cloned bottom border can therefore sit within that half-leading. Ordinary line heights leave this invisible.
• An inline box that wraps and is split at a column boundary has its unbroken width measured within each column rather than across both, so a gradient on such a box restarts in the second column. A block-level box is unaffected, and so is an inline box that only crosses page breaks.
• Where a line box of an inline straddles a page boundary, that one line’s decoration slice is drawn on both pages: once in its own place, and once near the top of the following page. Under slice the second copy is usually a thin band, partly clipped by the page edge; under clone it is a complete closed frame, drawn entirely inside the following page’s content.

Tables

Generated Content

CSS At-Rules