CSS Inline Layout Module Level 3

1. Introduction

This module defines inline layout, the CSS model for laying out a mixed stream of text and inline-level boxes, and defines controls for the block-axis alignment and sizing of this content within each line. It also adds a special layout mode for drop caps and similar initial letter styling.

Note: Line-breaking, justification, and other aspects of inline-axis positioning of inline-level content are handled in the CSS Text Module.

Many aspects of layout here depend on font metrics. While the relevant metrics exist in OpenType for Latin/Cyrillic/Greek and for CJK, they are missing for many other writing systems. For example, the visual top metric for Hebrew has no metric in the OpenType tables. For this module to work well for the world, we need fonts to provide the relevant metrics for all writing systems, and that means both that OpenType needs to allow such metrics and font designers need to provide accurate numbers. See issue and liaison statement.

1.1. Module Interactions

This module replaces and extends the CSS inline layout model and features defined in [CSS2] section 10.8.

1.2. Value Definitions

This specification follows the CSS property definition conventions from [CSS2] using the value definition syntax from [CSS-VALUES-3]. Value types not defined in this specification are defined in CSS Values & Units [CSS-VALUES-3]. Combination with other CSS modules may expand the definitions of these value types.

In addition to the property-specific values listed in their definitions, all properties defined in this specification also accept the CSS-wide keywords as their property value. For readability they have not been repeated explicitly.

2. Inline Layout Model

In inline layout, a mixed, recursive stream of text and inline-level boxes forming an inline formatting context within a block container are laid out by fragmenting them into a stack of line boxes. Within each line box, inline-level boxes are aligned to each other along the block axis, typically by the baselines of their text.

Any block container that directly contains inline-level content—​such as inline boxes, atomic inlines, and text sequences—​establishes an inline formatting context to lay out its contents using inline layout. The block container’s content edges form the containing block for each of the inline-level boxes participating in its inline formatting context.

The block container also generates a root inline box, which is an anonymous inline box that holds all of its inline-level contents. (Thus, all text in an inline formatting context is directly contained by an inline box, whether the root inline box or one of its descendants.) The root inline box inherits from its parent block container, but is otherwise unstyleable.

In an inline formatting context, content is laid out along the inline axis, ordered according to the Unicode bidirectional algorithm and its controls [CSS-WRITING-MODES-3] and distributed according to the typesetting controls in [CSS-TEXT-3]. Inline-axis margins, borders, and padding are respected between inline-level boxes (and their margins do not collapse). The resulting rectangular area that contains the boxes that form a single line of inline-level content is called a line box.

Note: Line boxes and inline boxes and inline-level boxes are each different things! See [CSS-DISPLAY-3] for an in-depth discussion of box types and related terminology.

2.1. Layout of Line Boxes

Line boxes are created as needed to hold inline-level content within an inline formatting context. When an inline box exceeds the logical width of a line box, or contains a forced line break, it is split (see CSS Text 3 § 5 Line Breaking and Word Boundaries) into several fragments [CSS-BREAK-3], which are partitioned across multiple line boxes. Like column boxes in multi-column layout [CSS-MULTICOL-1], line boxes are fragmentation containers generated by their formatting context, and are not part of the CSS box tree.

Note: Inline boxes can also be split into several fragments within the same line box due to bidirectional text processing. See [CSS-WRITING-MODES-3].

Line boxes are stacked as the direct contents of the block container box in its block flow direction and aligned within this container as specified by align-content [CSS-ALIGN-3]. Thus, an inline formatting context consists of a stack of line boxes. Line boxes are stacked with no separation (except as specified elsewhere, e.g. for float clearance) and they never overlap.

In general, the line-left edge of a line box touches the line-left edge of its containing block and the line-right edge touches the line-right edge of its containing block, and thus the logical width of a line box is equal to the inner logical width of its containing block (i.e. the block container’s content box). However, floating boxes or initial letter boxes can come between the containing block edge and the line box edge, reducing the space available to, and thus the logical width of, any such impacted line boxes. (See CSS 2 § 9.4.2 Inline formatting contexts/CSS 2 § 9.5 Floats and § 7 Initial Letters.)

The logical height of a line box is fitted to its contents once they have been block-axis aligned. This fit is controlled by line-height and line-fit-edge. The first/last line boxes in a block container may additionally be trimmed by text-box-trim.

2.2. Layout Within Line Boxes

As described above, user agents flow inline-level boxes into a stack of line boxes. Layout within each line box is performed, sizing and positioning each box fragment and line box independently, as follows:

1. Baseline Alignment: All in-flow inline-level boxes in the line box are aligned to each other in the block axis according to dominant-baseline and vertical-align. This is referred to as baseline alignment. Those with line-relative values for baseline-shift are assumed to be aligned so as to minimize the line box height.

2. Content Size Contribution Calculation: The layout bounds (i.e. the size contributions) of each inline-level box in the line box are calculated:

   • For atomic inlines such as replaced elements and inline blocks: this is their margin box.
   • For the root inline box, and for inline boxes with line-fit-edge: leading: this derived from their used line-height, ignoring any margin/border/padding; see § 5.3 Calculating the Logical Height Contributions (“Layout Bounds”) of Inline Boxes.
   • For other inline boxes: this is derived from their line-fit-edge metrics, and includes any margin/border/padding; see § 5.3 Calculating the Logical Height Contributions (“Layout Bounds”) of Inline Boxes.

3. Line Box Sizing: The line box’s logical height is sized to exactly include the aligned layout bounds of all its inline-level boxes.

4. Content Positioning: The root inline box’s aligned subtree and boxes line-relative values for baseline-shift are positioned within the line box.

   Define what to do for top/bottom/center aligned boxes that are taller than the rest of the content.

Note: Empty inline boxes still have margins, padding, borders, and a line-height, and thus influence these calculations just like boxes with content.

2.3. Phantom Line Boxes

Line boxes that contain no text, no preserved white space, no inline boxes with non-zero inline-axis margins, padding, or borders, and no other in-flow content (such as atomic inlines or ruby annotations), and do not end with a forced line break are phantom line boxes. Such boxes must be treated as zero-height line boxes for the purposes of determining the positions of any descendant content (such as absolutely positioned boxes), and both the line box and its in-flow content must be treated as not existing for any other layout or rendering purpose.

Firefox allows the inline boxes within a phantom line box to accept outline,which allows it to make focus rings visible. As in other browsers, all other properties that could make the element visible (e.g. box-shadow) seem to be ignored.

2.4. Painting Order

Except as specified for positioned boxes (see [CSS-POSITION-3]) inline-level boxes are painted in document order; the z-index property does not generally apply.

3. Baselines and Alignment Metrics

3.1. Introduction to Baselines

A baseline is a line along the inline axis of a line box along which individual glyphs of text are aligned. Baselines guide the design of glyphs in a font (for example, the bottom of most alphabetic glyphs typically align with the alphabetic baseline), and they guide the alignment of glyphs from different fonts or font sizes when typesetting.

Different writing systems prefer different baselines.

A well-constructed font contains a baseline table, which indicates the position of one or more baselines within the font’s design coordinate space. (The design coordinate space is scaled with the font size.)

The baseline table is a property of the font, and the positions of the various baselines apply to all glyphs in the font.

Different baseline tables can be provided for alignment in horizontal and vertical text. UAs should use the vertical tables in vertical typographic modes and the horizontal tables otherwise.

Note: Fonts can have more than one baseline table in each axis; the UA is responsible for choosing the appropriate table in consideration of font-language-override and the content language.

3.2. Baselines and Metrics

CSS uses the following text-based metrics as baselines for inline layout functions such as alignment, box sizing, and initial letter layout.

The CSSWG would like to know which baseline values are necessary for each property that uses them (dominant-baseline, alignment-baseline, text-box-edge, line-fit-edge, initial-letter-align): if any can be dropped, or any need to be added. See Issue 859.

alphabetic

Used in writing Latin, Cyrillic, Greek, and many other scripts, corresponds to the bottom of most, but not all, their characters, (such as “m”, “Ш”, “Δ”). Often represented as zero in font design coordinate systems; assigned to romn in OpenType and to bsln value zero in TrueType AAT.

cap-height

Corresponds to the top of capital letters (such as “T”, “Б”, “Σ”) in Latin, Cyrillic, Greek, etc. Calculated using sCapHeight in OpenType.

x-height

Corresponds to the top of short lowercase letters (such as “m”, “л”, “α”) in Latin, Cyrillic, Greek, etc. Calculated using sxHeight in OpenType.

x-middle

Corresponds to halfway between the alphabetic and x-height baselines.

ideographic-over

Corresponds to the line-over design edge of CJK (Han/Hangul/Kana) text. Assigned to idtp in OpenType.

ideographic-under

Corresponds to the line-under design edge of CJK (Han/Hangul/Kana) text. Assigned to ideo in OpenType.

central

Corresponds to the ideographic central baseline, halfway between the ideographic-under and ideographic-over baselines. Assigned to bsln value 1 in TrueType AAT.

ideographic-ink-over

Corresponds to the line-over ink edge of CJK (Han/Hangul/Kana) text. Assigned to icft in OpenType.

ideographic-ink-under

Corresponds to the line-under ink edge of CJK (Han/Hangul/Kana) text. Assigned icfb in OpenType.

hanging

Corresponds to hanging baseline from which characters in Tibetan and similar unicameral scripts with a strong but not absolute top edge seem to “hang”. Assigned to hang in OpenType and to bsln value 3 in TrueType AAT.

math

Corresponds to center baseline around which mathematical characters are designed. Assigned to math in OpenType and bsln value 4 in TrueType AAT.

text-over

Corresponds to the metric used as the line-over edge of an inline’s content box per [CSS2].

text-under

Corresponds to the metric used as the line-under edge of an inline’s content box per [CSS2].

em-over

Corresponds to a conceptual ascent normalized to ensure 1em between em-over and em-under. See A.1: Calculating Em-over and Em-under.

em-under

Corresponds to a conceptual descent normalized to ensure 1em between em-over and em-under. See A.1: Calculating Em-over and Em-under.

Note: These metrics are optical design metrics, and therefore do not necessarily correspond exactly to actual glyph outlines.

In general, these metrics are taken from the appropriate font, but if they are missing or need to be derived from a box rather than text, they must be synthesized, see § 3.3 Baselines of Glyphs and Boxes and Appendix A: Synthesizing Alignment Metrics.

3.2.1. Ascent and Descent Metrics

CSS assumes that every font has font metrics that specify a characteristic height above the baseline—​called the ascent metric—​and a characteristic depth below it—​called the descent metric—​which CSS uses for laying out text and boxes in an inline formatting context. Note that these are metrics of the font as a whole and need not correspond to the ascender and descender of any individual glyph.

Note: It is recommended that implementations that use OpenType or TrueType fonts use the metrics sTypoAscender and sTypoDescender from the font’s OS/2 table (after scaling to the current element’s font size) to find the ascent metric and descent metric for CSS layout. In the absence of these metrics, the "Ascent" and "Descent" metrics from the HHEA table should be used.

3.2.2. Line Gap Metrics

Font formats can allow for a font-recommended “line gap” or “external leading” metric. This metric is referred to as the line gap metric, and may be incorporated into the line box logical height calculations when line-height is normal as described in § 5.3 Calculating the Logical Height Contributions (“Layout Bounds”) of Inline Boxes.

Note: In OpenType, the line gap metric can be found as sTypoLineGap or hhea.lineGap.

UAs must floor the line gap metric at zero.

3.3. Baselines of Glyphs and Boxes

Each font, glyph, and inline-level box is assumed to have a baseline coordinate for each baseline type indicating that baseline’s position on its block axis. The set of such baselines is called its baseline set. The baseline from this set that is used to align the box or glyph within its alignment context is called its alignment baseline; the baseline used to align its content within itself is called its dominant baseline.

For an individual glyph, the baseline set derives from the font’s baseline table. For an inline box, it derives from its first available font regardless of whether the box actually contains any glyphs from that font. If the requisite metrics are missing from a font, the UA must synthesize them, see A.2: Synthesizing Baselines (and Other Font Metrics) for Text.

For other boxes, its baseline set is nominally derived from its contents in accordance with baseline-source and the rules of the formatting context in which it participates. For an atomic inline box with no baseline set in the inline formatting context’s inline axis its alignment baselines are synthesized from its margin box, see A.3: Synthesizing Baselines for Atomic Inlines.

4. Baseline Alignment

While most CSS formatting contexts position content by aligning boxes with respect to their container’s edges, inline layout positions boxes in the block axis by aligning them with respect to each other using their baselines.

More specifically, (unless using a line-relative shift value) each glyph or inline-level box is aligned in the block axis by positioning its alignment baseline to match the corresponding baseline of its parent (which is its alignment context), and then is potentially shifted from that position according to its post-alignment shift.

Note: Baseline alignment always matches corresponding baselines: alphabetic to alphabetic, hanging to hanging, mathematical to mathematical, etc.

When aligning a box, the alignment baseline is chosen according to its alignment-baseline and baseline-source values (see shorthand vertical-align), and defaults to matching the parent’s dominant-baseline. For a glyph, the alignment baseline is always determined by the parent’s dominant baseline.

Given following sample markup:

<p><span class="outer">Ap <span class="inner">ਜੀ</span></span></p>

And the following style rule:

.inner { font-size: 75%; }

The baseline sets of the parent (.outer) and the child (.inner) will not match up due to the font size difference. The child box is aligned to its parent by matching up their alphabetic baselines.

The alphabetic baseline is used here because by default a box’s alignment baseline matches the dominant baseline of its parent, and in horizontal typographic mode, the dominant baseline itself defaults to the alphabetic baseline.

If we add vertical-align: super to the .inner element from the example above, the same rules are used to align the .inner child to its parent; but in addition to the baseline alignment, the child is shifted to the superscript position.

4.1. Dominant Baselines: the dominant-baseline property

This property specifies the dominant baseline, which is the default baseline type used to align content within the box.

For inline boxes, the dominant baseline is used to align the box’s text (and, unless otherwise specified by vertical-align, any inline-level child boxes) by aligning each glyph/box’s corresponding baseline to the box’s own dominant baseline. For other boxes, it indicates the default alignment baseline of any boxes participating in baseline alignment in the box’s alignment context; see (alignment-baseline: baseline and [CSS-ALIGN-3]).

Values have the following meanings:

auto

Equivalent to alphabetic in horizontal writing modes and in vertical writing modes when text-orientation is sideways. Equivalent to central in vertical writing modes when text-orientation is mixed or upright.

However, in SVG text, the origin point of glyphs (used for coordinate-based glyph positioning) is always handled as for central in vertical writing modes.

text-bottom

Use the text-under baselines.

alphabetic

Use the alphabetic baselines.

ideographic

Use the ideographic-under baselines.

middle

Use the x-middle baselines; except under text-orientation: upright (where the alphabetic and x-height baselines are essentially meaningless) use the central baseline.

central

Use the central baselines.

mathematical

Use the math baselines.

hanging

Use the hanging baselines.

text-top

Use the text-over baselines.

See [CSS-WRITING-MODES-3] for an introduction to dominant baselines.

Define behavior for mixed vertical orientations that isn’t nonsensical when specified baseline isn’t central.

4.2. Transverse Box Alignment: the vertical-align property

This shorthand property specifies how an inline-level box is aligned within the line by specifying its alignment baseline type (alignment-baseline), baseline alignment preference (baseline-source), and post-alignment shift (baseline-shift) in a single declaration.

If first or last is specified, it sets baseline-source (which is otherwise reset to auto). Other values are as for the corresponding longhand properties, see below.

Authors should use this shorthand (vertical-align) instead of its longhands, unless specifically needing to cascade its longhands independently or (on SVG elements) to support legacy SVG implementations.

Note: vertical-align can also affect the alignment of table cells when align-content is normal. Specifically, top (baseline-shift: top) maps it to start, bottom (baseline-shift: bottom) to end, and otherwise middle (alignment-baseline: middle) to center. See CSS Box Alignment 3 § 5.1.1 Block Containers (Including Table Cells).

4.2.1. Alignment Baseline Source: the baseline-source longhand

When an inline-level box has more than one possible source for baseline information (such as for a multi-line inline block or inline flex container) this property specifies whether the first baseline set or last baseline set is preferred for alignment, indicating the box’s baseline alignment preference. Values have the following meanings:

auto

Specifies last-baseline alignment for inline-block, first-baseline alignment for everything else.

first

Specifies first-baseline alignment.

last

Specifies last-baseline alignment.

See CSS Box Alignment 3 § 9.1 Determining the Baselines of a Box for how to find the baselines of boxes other than inline boxes.

4.2.2. Alignment Baseline Type: the alignment-baseline longhand

This property specifies the box’s alignment baseline: the baseline used to align the box prior to applying its post-alignment shift (if applicable).

Values are defined as follows:

baseline

Use the dominant baseline choice of the parent.

text-bottom

Use the text-under baseline.

alphabetic

Use the alphabetic baseline.

ideographic

Use the ideographic-under baseline.

middle

In general, use the x-middle baselines; except under text-orientation: upright (where the alphabetic and x-height baselines are essentially meaningless) use the