CSS Inline Layout Module Level 3

W3C Working Draft,

More details about this document
This version:
https://www.w3.org/TR/2023/WD-css-inline-3-20230401/
Latest published version:
https://www.w3.org/TR/css-inline-3/
Editor's Draft:
https://drafts.csswg.org/css-inline-3/
Previous Versions:
History:
https://www.w3.org/standards/history/css-inline-3
Feedback:
CSSWG Issues Repository
Inline In Spec
Editors:
(Hachette Livre)
Elika J. Etemad / fantasai (Invited Expert)
Former Editor:
(Adobe)
Suggest an Edit for this Spec:
GitHub Editor
Issues list:
CSS3 Line Layout issues in GitHub

Abstract

The CSS formatting model provides for a flow of elements and text inside of a container to be wrapped into lines. This module describes box model for this inline layout model and defines the block-axis alignment and sizing of inline-level content, extending the model in [CSS2]. It also adds a special layout mode for drop-caps.

CSS is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, etc.

Status of this document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document was published by the CSS Working Group as a Working Draft using the Recommendation track. Publication as a Working Draft does not imply endorsement by W3C and its Members.

This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Please send feedback by filing issues in GitHub (preferred), including the spec code “css-inline” in the title, like this: “[css-inline] …summary of comment…”. All issues and comments are archived. Alternately, feedback can be sent to the (archived) public mailing list www-style@w3.org.

This document is governed by the 2 November 2021 W3C Process Document.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

The following features are at-risk, and may be dropped during the CR period:

“At-risk” is a W3C Process term-of-art, and does not necessarily imply that the feature is in danger of being dropped or delayed. It means that the WG believes the feature may have difficulty being interoperably implemented in a timely manner, and marking it as such allows the WG to drop the feature if necessary when transitioning to the Proposed Rec stage, without having to publish a new Candidate Rec without the feature first.

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 sequencesestablishes 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.1 § 9.4.2 Inline formatting contexts/CSS 2.1 § 9.5 Floats and § 6 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 text-box-edge. The first/last line boxes in a block container may additionally be trimmed by text-box-trim.

diagram showing inline boxes split across line boxes as described above
Inline Layout Box Model

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:

  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. “Invisible” Line Boxes

Line boxes that contain no text, no preserved white space, no inline boxes with non-zero 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 invisible 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.

What’s invisible?

Such invisible line boxes, which can still contain unstyled empty inline boxes, out-of-flow boxes, and/or collapsed document white space, are ignored, for example, for:

Firefox allows the inline boxes within an invisible 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.

Picture of alphabetic text in two font sizes with the baseline and em-boxes

Alphabetic text in two font sizes with the baseline and em-boxes

Different writing systems prefer different baselines.

Latin prefers the alphabetic baseline,
		          on top of which most letters rest,
		          though some letters have descenders that dangle below it.
		          Indic scripts are sometimes typeset with a hanging baseline,
		          since their glyph shapes appear to be hanging from a horizontal line.
		          Han-based systems, whose glyphs are designed to fill a square,
		          tend to align on their bottoms or through their centers.

Preferred baselines in various writing systems

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.)

In a well-designed mixed-script font, the glyphs are positioned in the coordinate space to harmonize with one another when typeset together. The baseline table is then constructed to match the shape of the glyphs, each baseline positioned to match the glyphs from its preferred scripts.

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, 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 metricand a characteristic depth below it—called the descent metricwhich 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.

In this example, the distance between each baseline in the baseline set
			          is compacted 75% in the span with a 75% font size.
			          Their alphabetic baselines, however, line up.

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.

In this example, the resulting alignment is equivalent to
			             shifting the parent baseline table upwards by its superscript offset,
			             and then aligning the child’s alphabetic baseline
			             to the shifted position of the parent’s alphabetic baseline.

4.1. Dominant Baselines: the dominant-baseline property

Name: dominant-baseline
Value: auto | text-bottom | alphabetic | ideographic | middle | central | mathematical | hanging | text-top
Initial: auto
Applies to: block containers, inline boxes, table rows, grid containers, flex containers, and SVG text content elements
Inherited: yes
Percentages: N/A
Computed value: specified keyword
Canonical order: per grammar
Animation type: discrete

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

Name: vertical-align
Value: [ first | last] || <'alignment-baseline'> || <'baseline-shift'>
Initial: baseline
Applies to: see individual properties
Inherited: no
Percentages: N/A
Computed value: see individual properties
Animation type: see individual properties
Canonical order: per grammar

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

Name: baseline-source
Value: auto | first | last
Initial: auto
Applies to: inline-level boxes
Inherited: no
Percentages: N/A
Computed value: specified keyword
Canonical order: per grammar
Animation type: discrete

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

Name: alignment-baseline
Value: baseline | text-bottom | alphabetic | ideographic | middle | central | mathematical | text-top
Initial: baseline
Applies to: inline-level boxes, flex items, grid items, table cells, and SVG text content elements
Inherited: no
Percentages: N/A
Computed value: specified keyword
Canonical order: per grammar
Animation type: discrete

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 central baseline instead.
central
Use the central baseline.
mathematical
Use the math baseline.
text-top
Use the text-over baseline.

When performing baseline alignment, these values specify which baseline of the box is aligned to the corresponding baseline of its alignment context. (In an inline formatting context, inline-level box fragments and glyphs share an alignment context established by their parent inline box fragment along its inline axis. For other formatting contexts, see CSS Box Alignment 3 § 9.2 Baseline Alignment Grouping.) In SVG text layout, these values instead specify the baseline that is aligned to the SVG current text position.

4.2.2.1. Legacy Values for SVG

SVG implementations may support the following aliases in order to support legacy content:

text-before-edge = text-top
text-after-edge = text-bottom

These values are not allowed in the vertical-align shorthand.

4.2.3. Post-Alignment Shift: the baseline-shift longhand

Name: baseline-shift
Value: <length-percentage> | sub | super | top | center | bottom
Initial: 0
Applies to: inline-level boxes and SVG text content elements
Inherited: no
Percentages: refer to the used value of line-height
Computed value: the specified keyword or a computed <length-percentage> value
Canonical order: per grammar
Animation type: by computed value type

This property specifies the box’s post-alignment shift. The baseline-relative shift values <length-percentage>, sub, super shift the box relative to its baseline-aligned position, whereas the line-relative shift values top, center, and bottom shift the inline box and its contents relative to the bounds of its line box.

Authors should use the vertical-align shorthand, which has existed since CSS1, instead of this baseline-shift longhand (except in SVG content, where conversely baseline-shift is more widely-supported in legacy user agents).

Values have the following meanings:

<length>
Raise (positive value) or lower (negative value) by the specified length.
<percentage>
Raise (positive value) or lower (negative value) by the specified percentage of the line-height.
sub
Lower by the offset appropriate for subscripts of the parent’s box. The UA may use the parent’s font metrics to find this offset; otherwise it defaults to dropping by one fifth of the parent’s used font-size.
super
Raise by the offset appropriate for superscripts of the parent’s box. The UA may use the parent’s font metrics to find this offset; otherwise it defaults to raising by one third of the parent’s used font-size.
top
Align the line-over edge of the aligned subtree with the line-over edge of the line box.
center
Align the center of the aligned subtree with the center of the line box.
bottom
Align the line-under edge of the aligned subtree with the line-under edge of the line box.

The aligned subtree of an inline box contains the layout bounds of that box and the aligned subtrees of all child inline boxes whose computed alignment-baseline value is not itself a line-relative shift value. The line-over edge of the aligned subtree is the highest over edge of the layout bounds in the subtree, and the line-under edge is analogously the lowest.

The line-relative shift values don’t fit perfectly in the dichotomy between alignment-baseline and baseline-shift. There’s decent arguments for either option. They’re currently drafted here, but if there’s a strong argument to move them, please file an issue for consideration.

4.2.3.1. Legacy Values for SVG

User agents may additionally support the keyword baseline as computing to 0 if is necessary for them to support legacy SVG content. This value is not allowed in the vertical-align shorthand.

We would prefer to remove the baseline value, and are looking for feedback from SVG user agents as to whether it’s necessary.

5. Logical Heights and Inter-line Spacing

The block-axis sizing of a line box depends on the sizes and alignment of its inline-level contents. This sizing is controlled by the line-height, text-box-edge, text-box-trim, and inline-sizing properties.

5.1. Line Spacing: the line-height property

Name: line-height
Value: normal | <number> | <length-percentage>
Initial: normal
Applies to: non-replaced inline boxes and SVG text content elements
Inherited: yes
Percentages: computed relative to 1em
Computed value: the specified keyword, a number, or a computed <length> value
Canonical order: per grammar
Animation type: by computed value type

This property specifies the box’s preferred line height, which is used in calculating its “layout bounds”, i.e. its contribution to the logical height of its line box. (See § 5.3 Calculating the Logical Height Contributions (“Layout Bounds”) of Inline Boxes.)

Note: Because it applies to the root inline box when specified on a block container, line-height effectively establishes the minimum height of the block’s line boxes.

Values for this property have the following meanings:

normal
Determine the preferred line height automatically based on font metrics.
<length>
The specified length is used as the preferred line height. Negative values are illegal.
<number>
The preferred line height is this number multiplied by the element’s computed font-size. Negative values are illegal. The computed value is the same as the specified value.
<percentage>
The preferred line height and computed value of the property is this percentage of the element’s computed font-size. Negative values are illegal.

Note: Metrics from fonts other than the first available font only impact the layout bounds of an inline box with line-height: normal.

The three rules in the example below have the same used line height:
div { line-height: 1.2; font-size: 10pt }     /* number */
div { line-height: 1.2em; font-size: 10pt }   /* length */
div { line-height: 120%; font-size: 10pt }    /* percentage */

However, they inherit differently: the first one inherits as a number, which will lead to different line heights if descendants have different font sizes; the last two as inherit as absolute lengths, which will not be influenced by the font size on descendants.

The fact that percentages compute to lengths is annoying. See also Issue 3118 and Issue 2165.

Note: When text-box-edge is leading, the margins, borders, and padding of inline boxes do not affect the line box’s height calculation. However, they are still rendered around these boxes. This means that if the size specified by line-height is less than the size of the box, backgrounds and borders can “bleed” into adjoining line boxes, potentially obscuring earlier content.

5.2. Inline Box Edge Metrics: the text-box-edge property

Name: text-box-edge
Value: leading | [ text | cap | ex | ideographic | ideographic-ink ] [ text | alphabetic | ideographic | ideographic-ink ]?
Initial: leading
Applies to: inline boxes
Inherited: yes
Percentages: N/A
Computed value: the specified keyword
Canonical order: per grammar
Animation type: discrete

This is an early draft of a proposal, and might change significantly as design critiques and use cases are registered and various details and interactions with other properties are worked out. Do not implement (yet).

Inline boxes, whose primary purpose is to contain text, are sized in the block axis based on their font metrics. The text-box-edge property controls which metrics are used.

The chosen metrics are used as the basis for the layout bounds of the inline box (if it is not the root inline box). The text-box-trim property can be used in conjunction to match the content edges to these same metrics.

The first value specifies the text over edge; the second value specifies the text under edge. If only one value is specified, both edges are assigned that same keyword if possible; else text is assumed as the missing value.

Do we need longhands or is this shorthand enough? [Issue #5236]

Note: The leading and text values rely on the font ascent and descent to make sure the text fits. Other values are more likely to result in overlap or overflow caused by ascents above the specified metrics (such as for diacritics), so authors using these values need to be careful to provide sufficient spacing for the text.

Values have the following meanings:

leading
Use the ascent/descent plus any positive half-leading. Margin/padding/border is ignored for the purpose of sizing the line box.
text
Use the text-over baseline/text-under baseline.
cap
Use the cap-height baseline.
ex
Use the x-height baseline.
ideographic
Use the ideographic-over baseline/ideographic-under baseline.
ideographic-ink
Use the ideographic-ink-over baseline/ideographic-ink-under baseline.
alphabetic
Use the alphabetic baseline.

Unless text-box-edge is leadingin which case the box’s own line-height is used to add spacing—the box’s margin, padding, and border also contribute to the layout bounds.

Note: Although only leading applies positive half-leading, in order to allow text to be set tightly, all values apply negative half-leading, see § 5.3 Calculating the Logical Height Contributions (“Layout Bounds”) of Inline Boxes. Half-leading is applied equally to both sides of the text; for more precise overlap control authors can use text-box-edge: text together with negative margins on the affected text.

Three different values of the text-box-edge property.
The text-box-edge property, showing values for leading, cap, and ex. The red lines indicate the layout bounds of the inline box.

When text-box-edge is leading, vertical rhythm can be broken any time there is a change in font metrics or vertical alignment within a paragraph.

Other values are more likely to give consistent line spacing—as long as there is enough leading added that the half-leading on the root inline is large enough to accommodate the specified metrics of any descendants. The line box will still grow, however, to accommodate content that would otherwise overflow, to avoid overlap between lines.

5.3. Calculating the Logical Height Contributions (“Layout Bounds”) of Inline Boxes

The contribution of an inline box to the logical height of its line box, here referred to as its layout bounds, is always calculated with respect to its own text metrics, as described below, and is controlled by text-box-edge and line-height. The sizes and positions of child boxes do not influence its layout bounds (nor its own logical height, for that matter, see inline-sizing).

Note: The layout bounds need not correspond to the box’s edges.

To find the layout bounds of an inline box, the UA must first align all the glyphs directly contained in the inline box to each other by their dominant baselines. (See § 3.3 Baselines of Glyphs and Boxes.) If the inline box contains no glyphs at all, or if it contains only glyphs from fallback fonts, it is considered to contain a “strut” (an invisible glyph of zero width) with the metrics of the box’s first available font.

For each glyph (including the “strut”), A represents its ascent above the baseline; D represents its descent below. Unless text-box-edge specifies a different metric to use, A refers to the ascent metric (for the given font at its given size) and D to the descent metric, each adjusted to account for the dominant baseline’s offset from zero. If line-height computes to normal and either text-box-edge is leading or this is the root inline box, the font’s line gap metric may also be incorporated into A and D by adding half to each side as half-leading.

When its computed line-height is normal, the layout bounds of an inline box encloses all its glyphs, going from the highest A to the deepest D. (Note that glyphs in a single box can come from different fonts and thus might not all have the same A and D.)

When its computed line-height is not normal, its layout bounds are derived solely from metrics of its first available font (ignoring glyphs from other fonts), and leading is used to adjust the effective A and D to add up to the used line-height. Calculate the leading L as L = line-height - (A + D). Half the leading (its half-leading) is added above A of the first available font, and the other half below D of the first available font, giving an effective ascent above the baseline of A′ = A + L/2, and an effective descent of D′ = D + L/2. However, if text-box-edge is not leading and this is not the root inline box, if the half-leading is positive, treat it as zero. The layout bounds exactly encloses this effective A′ and D′.

Note: L may be negative.

Additionally, when text-box-edge is not leading, the layout bounds are inflated by the sum of the margin, border, and padding on each side.

In Quirks Mode [QUIRKS], any inline box fragment that has zero borders and padding and that does not directly contain text or preserved white space [CSS-TEXT-3] is ignored when sizing the line box.

5.4. Half-Leading Control: the text-box-trim property

To ensure consistent spacing in the basic case of running text, CSS line layout introduces leading both above and below the text content of each line as needed to ensure its line-height. In addition, the ascent and descent font metrics themselves often include extra space above and below the most typical glyph shapes in order to accommodate occasional characters and diacritics that ascend or descend beyond the typical bounds. This prevents adjacent lines of text from overlapping each other. However, all this extra spacing interferes with visual alignment and with control over effective (visually-apparent) spacing.

The text-box-trim property allows trimming this additional space above and below the first and last lines of a block, allowing more precise control over spacing around the glyphs. Moreover, by relying on font metrics rather than hard-coded lengths, it allows content to be resized, rewrapped, and rendered in a variety of fonts while maintaining that spacing.

A common problem is vertical centering. It’s easy to vertically center the text container to an icon, but because the visual boundaries of Latin text are the cap height and the alphabetic baseline, rather than the ascent and descent, this often doesn’t yield the intended visual effect.

Consider some Latin text placed to the right of an image,
			          to be centered between its top and bottom.
			          Measuring from the top of the image to the top of the text box yields 13px;
			          likewise measuring from the bottom of the image to the bottom of the text box yields 13px,
			          theoretically perfectly centering the text.
			          However, measuring from the top of the image to the cap-height yields 21px;
			          and measuring from the bottom to the alphabetic baseline yields 19px,
			          showing that visually the text is not actually centered.
Measuring to the top/bottom of the text may yield equal results, but measuring to the visual bounds shows that it is not visually centered.

To center the text visually, it’s necessary to assume the cap height and alphabetic baseline as the top and bottom edges of the text, respectively.

If the text were visually centered,
			          the distance between the top of the image and the cap height would be 20px,
			          and the distance between the bottom of the image and the alphabetic baseline would be equally 20px.
Measuring to the cap height / alphabetic baseline instead of the ascent / descent and equalizing those distances visually centers the text.

By using text-box-trim to strip out the spacing above the cap height and below the alphabetic baseline, centering the box actually centers the text; and does so reliably, regardless of what font is used to render it.

Even though different fonts have different cap heights, by using the font’s metric rather than a magic number, the layout intention is met even as the font is changed.
Name: text-box-trim
Value: none | start | end | both
Initial: none
Applies to: block containers and inline boxes
Inherited: no
Percentages: N/A
Computed value: the specified keyword
Canonical order: per grammar
Animation type: discrete

This is an early draft of a proposal, and is likely to change significantly as design critiques and use cases are registered. Values and property names may be added, dropped, and/or renamed, and the overall syntax or behavior may change, particularly in response to authoring and robustness considerations for handling descendant boxes. Do not implement (yet).

On inline boxes, specifies whether to trim the content box to match its corresponding text-box-edge metric.

Should inline boxes automatically do this? And/or is it better for line sizing and content-box sizing to be separably controlled?

On block containers, specifies whether to trim half-leading at the start/end of its content to the corresponding text-box-edge metric to better match the box’s content edge to its text content.

Note: Content and ink overflowing a box due to non-initial values of text-box-trim is handled the same as content that would overflow the box or line box otherwise.

This property has no effect when text-box-edge is leading.

Values have the following meanings:

none
No special handling of the first/last line box when applied to a block container.

When applied to an inline box, specifies that the over/under content edges coincide with the text-over/text-under baselines regardless of text-box-edge (which nonetheless still affects line box sizing).

start
For block containers: trim the block-start side of the first formatted line to the corresponding text-box-edge metric of its root inline box. If there is no such line, or if there is intervening non-zero padding or borders, there is no effect.

For inline boxes: trims the block-start side of the box to match its content edge to the metric specified by text-box-edge (treating leading as text).

end
For block containers: trim the block-end side of the last formatted line to the corresponding text-box-edge metric of its root inline box. If there is no such line, or if there is intervening non-zero padding or borders, there is no effect.

For inline boxes: trims the block-end side of the box to match its content edge to the metric specified by text-box-edge (treating leading as text).

both
Specifies the behavior of start and end simultaneously.

Note: The block-end side does not coincide with the line-under side when writing-mode is vertical-lr.

5.5. Inline Box Drawing Height: the inline-sizing property

Name: inline-sizing
Value: normal | stretch
Initial: normal
Applies to: inline boxes, but not ruby container boxes nor internal ruby boxes
Inherited: yes
Percentages: n/a
Computed value: specified keyword
Canonical order: per grammar
Animation type: discrete

This has a confusing name. We need a new name. [Issue #5189]

This property specifies how the logical height of the content area of an inline box is measured in relation to its contents. It has no effect on the size or position of the box’s contents, the line box, or any other content.

Values have the following meanings:

normal
The content area of the inline box is sized and positioned to fit (possibly hypothetical) text from its first available font. This specification does not specify how. A UA may, e.g., use the maximum ascender and descender of the font. (This would ensure that glyphs with parts above or below the em-box still fall within the content area, but leads to differently sized boxes for different fonts.)

Note: If more than one font is used (which happen when glyphs are found in different fonts), the logical height of the content area is not affected by the glyphs from the fallback fonts, and only depends on the first available font. However, these fallback glyphs can still affect the line box size when line-height is normal; see § 5.3 Calculating the Logical Height Contributions (“Layout Bounds”) of Inline Boxes.

stretch
Once the line box has been sized and its contents positioned as for normal, the inline box’s box edges are shifted such that its over/under margin edges coincide with the corresponding line box’s edges, stretching the inline box’s inner logical height so that its block-axis outer size fills the line box. (The sizes and positions of its in-flow contents are not affected.)

Note: The height property does not apply to inline boxes.

Note: The line-height has no impact on the size of an inline box, it only affects its contribution to the logical height of its line box.

6. Initial Letters

The editors would appreciate any examples of drop initials in non-western scripts, especially Indic scripts.

6.1. An Introduction to Initial Letters

This section is non-normative.

Large, decorative letters have been used to start new sections of text since before the invention of printing. In fact, their use predates lowercase letters entirely.

6.1.1. Drop Initial

A dropped initial (or “drop cap”) is a larger-than-usual letter at the start of a paragraph, with a baseline at least one line lower than the first baseline of the paragraph. The size of the drop initial is usually indicated by how many lines it occupies. Two- and three-line drop initials are very common.

3-line drop cap with E Acute
Three-line drop initial with E acute. Since the cap-height of the drop initial aligns with the cap-height of the main text, the accent extends above the paragraph.

The exact size and position of a dropped initial depends on the alignment of its glyph. Reference points on the drop cap must align precisely with reference points in the text. The alignment constraints for drop initials depend on the writing system.

In Western scripts, the top reference points are the cap height of the initial letter and of the first line of text. The bottom reference points are the alphabetic baseline of the initial letter and the baseline of the Nth line of text. The figure below shows a simple two-line drop cap, with the relevant reference lines marked.

drop cap showing alignment
Two-line drop cap showing baselines (green lines), cap-height (red line), and ascender (cyan line).

In Han-derived scripts, the initial letter extends from the block-start edge of the glyphs on the first line to the block-end edge of the glyphs on the Nth line.

Japanese Vertical Initial
Two-line drop initial in vertical writing mode

In certain Indic scripts, the top alignment point is the hanging baseline, and the bottom alignment point is the text-after-edge.

Devanagari initial letter
Devanagari initial letter aligned with hanging baseline. Alignment points shown in red.

6.1.2. Sunken Initial Letters

Some styles of drop initials do not align with the first line of text. A sunken initial (or “sunken cap”) both sinks below the first baseline, and extends above the first line of text.

sunken drop initial
Sunken cap. The letter drops two lines, but is the size of a three-line initial letter.

6.1.3. Raised Initial Letters

A raised initial (often called a “raised cap” or “stick-up cap”) “sinks” to the first text baseline.

Note: A proper raised initial has several advantages over simply increasing the font size of a first letter. The line spacing in the rest of the paragraph will not be altered, but text will still be excluded around large descenders. And if the size of raised initial is defined to be an integral number of lines, implicit baseline grids can be maintained.

raised cap
Raised cap. The initial letter is the size of a 3-line initial, but does not drop.

6.2. Selecting Initial Letters

This section is non-normative.

Initial letters are typically a single letter, although they may include punctuation or a sequence of characters which are perceived by the user to be a single typographic unit. The ::first-letter pseudo-element, defined in [SELECT] and [CSS-PSEUDO-4], can be used to select the character(s) to be formatted as initial letters.

Authors who need more control over which characters are included in an initial letter, or who want to apply initial-letter formatting to replaced elements or multiple words can alternately apply the initial-letter property to the first inline-level child of a block container.

<p>This paragraph has a dropped “T”.
<p><img alt="H" src="illuminated-h.svg">ere we have an illuminated “H”.
<p><span>Words may also</span> be given initial letter styling at the beginning of a paragraph.
::first-letter, /* style first paragraph’s T */
img, /* style illuminated H */
span /* style phrase inside span */
{ initial-letter: 2; }

Note that since ::first-letter selects punctuation before or after the first letter, these characters are included in the initial letter when ::first-letter is used.

Paragraph showing both opening quote and first letter set as three-line drop cap
The ::first-letter pseudo-element selects the quotation mark as well as the “M”.

Should there be a way to opt out of this behavior? See GitHub Issue 310.

6.3. Creating Initial Letters: the initial-letter property

Name: initial-letter
Value: normal | <number [1,∞]> <integer [1,∞]> | <number [1,∞]> && [ drop | raise ]?
Initial: normal
Applies to: certain inline-level boxes and ::first-letter and inside ::marker boxes (see prose)
Inherited: no
Percentages: N/A
Computed value: the keyword normal or a number paired with an integer
Canonical order: per grammar
Animation type: by computed value type

This property specifies the size and sink for dropped, raised, and sunken initial letters as the number of lines spanned.

For example, the following code will create a 2-line dropped initial letter at the beginning of each paragraph that immediately follows a second-level heading:
h2 + p::first-letter { initial-letter: 2; }

It takes the following values:

normal
No special initial letter effect. Text behaves as normal.
<number [1,∞]>
This first argument defines the size of the initial letter in terms of how many lines it occupies. Values less than one are invalid.
<integer [1,∞]>
This optional second argument defines the number of lines the initial letter should sink. A value of 1 indicates a raised initial; values greater than 1 indicate a sunken initial. Values less than one are invalid.
raise
Computes to an initial letter sink of 1.
drop
Computes to an initial letter sink equal to the initial letter size floored to the nearest positive whole number.

If the initial letter sink value is omitted, drop is assumed.

Values other than normal cause the affected box to become an initial letter box, which is an in-flow inline-level box with special layout behavior.

Here are some examples of initial-letter usage:
initial-letter: 3
initial-letter: 3 3
initial-letter: 3 drop
initial-letter: drop 3
Represents a dropped initial 3 lines high, 3 lines deep.

3 lines high, 3 lines deep

initial-letter: 3 2
Represents a sunken initial 3 lines high, 2 lines deep.

3 lines high, 2 lines deep

initial-letter: 3 1
initial-letter: 3 raise
initial-letter: raise 3
Represents a raised initial 3 lines high, 1 line deep.

3 lines high, 1 line deep

initial-letter: 2.51 3
The size of the initial letter does not have to be an integral number of lines. In this case only the top aligns.

Non-integral initial letter that only aligns at base

In conjunction with other CSS properties, initial-letter can be used to create “adjacent initial letters,” where the initial letter is adjacent to the text:
p::first-letter {
  initial-letter: 3;
  color: red;
  width: 5em;
  text-align: right;
  margin-left: -5em;
}

p {
  margin-left: 5em;
}
Initial letter adjacent to text

6.3.1. Applicability

To give authors more control over which characters can be styled as an initial letter and to allow the possibility of multi-character initial letters (such as for first word or first phrase styling), the initial-letter property applies not just to the CSS-defined ::first-letter pseudo-element, but also to inside-positioned ::marker pseudo-elements and to inline-level boxes that are placed at the start of the first line. Specifically, initial-letter applies to any inline-level boxincluding any such ::first-letter or ::marker box—that is the first child of its parent box and whose ancestors (if any) that are descendants of its containing block are all first-child inline boxes that have a computed initial-letter value of normal.

For example, the <span>, <em>, and <b> elements in the following example are "first-most inline-level descendants" of the <p>, but the <strong> element is not:
<p><span><em><b>This</b> phrase</em> is styled
<strong>specially</strong>.</span> …

If we apply the following rules:

em { initial-letter: 2; }
b, strong { initial-letter: 3; }

The initial-letter property will take effect only on the <em>. The styling on <b> is ignored, as it has an ancestor already styled as an initial letter; and the styling on <strong> is ignored because it is a second sibling.

The result might be rendered as

“This phrase” becomes the dropped text spanning two lines, the remainder of the text wrapping alongside.

If initial-letter is applied to an inline-level box that is not positioned at the start of the line due to bidi reordering or which is otherwise preceded by other inline-level content, its used value is normal, and it is not formatted as an initial letter.

The effect of the initial-letter property is undefined on children of ruby base container boxes and on ruby container boxes.

Note: The initial-letter property cannot apply to any element whose float is not none or position is not static, because these values cause its display to compute to block.

6.4. Alignment of Initial Letters: the initial-letter-align property

As mentioned earlier, the alignment of initial letters depends on the script used. The initial-letter-align property can be used to specify the proper alignment.

Name: initial-letter-align
Value: [ border-box? [ alphabetic | ideographic | hanging | leading ]? ]!
Initial: alphabetic
Applies to: certain inline-level boxes and ::first-letter and inside ::marker boxes (see prose)
Inherited: yes
Percentages: N/A
Computed value: specified keyword(s)
Canonical order: per grammar
Animation type: discrete

This property specifies the alignment points used to size and position an initial letter. Two sets of alignment points are necessary: the over and under alignment points of the initial letter are matched to corresponding over and under points of the root inline box.

Values have the following meanings:

alphabetic
Use the cap-height and alphabetic baselines of the surrounding text to align the initial letter.
ideographic
Use the ideographic-ink-over and ideographic-ink-under baselines of the surrounding text to align the initial letter.
hanging
Use the hanging and alphabetic baselines of the surrounding text to align the initial letter.
leading
Use the over/under half-leading edges (i.e. ascent/descent + half-leading) of the surrounding text to align the initial letter.

Note: This will essentially match the edges of the initial letter to middle of the line gap above/below the first/last impacted lines, which is an effect sometimes used in certain types of Indic typesetting [ILREQ].

border-box
Use the initial letter box’s line-under and line-over border edges as the over and under alignment points, respectively.
The vertical writing mode example earlier (in § 6.1 An Introduction to Initial Letters) could be coded as:
span.initial {
  initial-letter: 2;
  initial-letter-align: ideographic;
}

Except when border-box is specified, the alignment points of the initial letter are automatically determined from its contents:

  1. If the initial letter is an atomic inline, use its over and under content-box edges.
  2. Else if the initial letter contains any character from the Han, Hangul, Kana, or Yi Unicode scripts, use the ideographic-ink-over and ideographic-ink-under baselines.
  3. Else if the initial letter contains any character from the Devanagari, Bengali, and Gurmukhi Unicode scripts, use the hanging and alphabetic baselines.
  4. Else use the cap-height and alphabetic baselines.
Correct alignment of initial letter in scripts such as Hebrew and Thai is currently not possible because OpenType lacks corresponding metrics. (Issue 5244)
Hebrew 2-line drop-letter alignment using the hebrew-top and alphabetic baselines

Note: The ordering of keywords in this property is fixed in case border-box is expanded to [ border-box | alphabetic | ideographic | hanging ] to allow explicitly specifying the initial letter’s alignment points.

6.4.1. UA Default Stylesheet for initial-letter-align

In order to provide the better behavior by default, UAs must include in their default UA style sheet the following rules:

[lang]:lang(zh, ja, ko, ii) {
  initial-letter-align: ideographic;
}
[lang]:lang(hi, mr, ne, pi, kok, brx, mai, sd, sa) {
  initial-letter-align: hanging;
}
/* Script tags override language tags */
[lang]:lang('*-Latn', '*-Cyrl') {
  initial-letter-align: alphabetic;
}
[lang]:lang('*-Hani', '*-Hant', '*-Hans') {
  initial-letter-align: ideographic;
}

This only covers the most common cross-linguistic transcription systems. Should we include any other / all script tags in the UA style sheet?

6.5. Initial Letter Layout

There are two types of initial letter boxes: those that arise from non-replaced inline boxes and those that arise from atomic inlines.

For the non-atomic inline initial letter, the box and its contents participate in the same inline formatting context as the line on which it occurs, and a lot of special rules apply to give the expected sizing and alignment.

For an atomic initial letter, however, which is either a replaced element or which establishes an independent formatting context for its contents, the sizing of the box (aside from its automatic size in the block axis) and layout of the contents within the box follows the usual rules: it is primarily the positioning of the box which is special.

6.5.1. Properties Applying to Initial Letters

All properties that apply to an inline box also apply to an inline initial letter except for vertical-align and its sub-properties, font-size, line-height, text-box-edge, and inline-sizing. Additionally, all of the sizing properties and box-sizing also apply to initial letters (see [css-sizing-3]).

All properties that apply to an atomic inline also apply to the atomic inline when styled as an initial letter, except for vertical-align and its sub-properties.

6.5.2. Margins, Borders, and Padding

Initial letters can be styled with margins, padding, and borders just like any other box. Unless initial-letter-align is border-box, its vertical alignment and font sizing are not affected. However the effective exclusion area, which is typically the initial letter’s margin box (see initial-letter-wrap) is affected.

When padding and borders are zero, the initial letter may be kerned; see below.

6.5.3. Font Sizing of Initial Letters

For an inline initial letter, the font size used for sizing the initial letter contents is calculated to fulfill its specified size (see initial-letter) as anchored by its specified alignment points (see initial-letter-align). Note that no layout is required in this calculation: it is based only on computed values and font metrics. These used font size calculations do not affect the computed font-size, and therefore have no effect on the computation of em length values, etc.

What about inheritance to descendants? [Issue #4988]

The line height used in these calculations is the line-height of the containing block (or, in the case where a baseline grid is in use, the baseline-to-baseline spacing required by the baseline grid [CSS-LINE-GRID-1]). The contents of the lines spanned, and therefore any variation in their heights and positions, is not accounted for.

Text underlay shows how initial letter alignment
		          is not affected by the content of the spanned lines.

For an N-line drop initial in a Western script, the cap-height of the letter needs to be (N – 1) times the line-height, plus the cap-height of the surrounding text. Note this height is not the font size of the drop initial.

Actually calculating this font size is tricky. For an N-line drop initial, we find the drop initial font size to be:

Font size of drop cap = ((N-1) * line-height + [cap-height of para] * [font size of paragraph])/[cap-height ratio of drop initial font]

Update this calculation to be a) generic across writing systems / alignment points and b) handle non-integer sizes.

A three-line drop initial in Adobe Minion Pro would have a font size of 61.2pt given 12pt text, 16pt line-height, and a cap-height of 651/1000 (from the font’s OS/2 table).

For an atomic initial letter, the used font size is the computed font size as usual.

6.5.4. Shaping and Glyph Selection

When initial-letter is not normal, an inline initial letter is isolated for glyph shaping; however the text after it should shape across the inline initial letter box’s boundaries, assuming its presence as part of the first line’s text content. (See CSS Text 3 § 7.3 Shaping Across Element Boundaries.) For example, if the first letter of the word “يحق” were styled with initial-letter: 2 1, the first letter would be styled in its isolated form “ي”, as the initial letter, followed by the medial/final-form “ﺤﻖ”, which assumes it is preceded by the initial letter’s contents as normal text.

Two-line Arabic drop-cap showing isolated form of the first letter, connected form of the rest of the word.
Two-line Arabic “Drop-cap”

6.5.5. Sizing the Initial Letter Box

For an inline initial letter, if the initial letter’s preferred width/preferred height is definite, use that value (clamped as required by the min size and max size properties, and handling box-sizing as required) for that dimension of the box.

Otherwise it is considered to have an automatic size in that dimension and its content box is sized to fit both:

However, if its block-start padding and border are both zero, then its block-start content edge instead coincides with its over alignment point exactly, and any content overflowing above that point is ignored for the purpose of layout.

Note: If an inline initial letter has ascenders above its over alignment point, and the author has not provided sufficient margin on either the initial letter itself or its containing block, then those ascenders might collide with preceding content.

Note: It might be nice to automatically provide the necessary spacing by treating such ascenders as a margin that can collapse with the margin of the containing block, and thus guarantee the requisite spacing without imposing any additional space unless it becomes actually necessary. Depending on implementation complexity, this option may be explored in the future; but in the meantime, authors need to be careful to provide the requisite spacing explicitly.

Should the hanging punctuation be included in the box instead (so that the box is drawn around the punctuation when it is made visible through borders/background), but rather only excluded when positioning the box (so that the initial letter remains flush, with the hanging punctuation properly hanging)? See discussion.

For atomic initial letters, sizing follows the usual rules for that type of atomic inline. However, if the box has an automatic block size (auto), then its block size is determined as for an inline initial letter with border-box alignment, and is definite.

6.5.6. Alignment Within an Initial Letter Box

By default (i.e. under automatic sizing), the content box of an inline initial letter is fitted exactly to its content, and alignment properties like text-align or align-content do not apply. However, if the box is not sized automatically:

6.6. Initial Letter Positioning and Spacing

6.6.1. Block-axis Positioning

In the block axis, the initial letter is positioned with respect to the line box in which it originates as required to satisfy its alignment (initial-letter-align) and specified sink (initial-letter):

Note: An initial letter is essentially positioned such that it would sink the number of lines specified by initial-letter’s second argument and align to the requisite under alignment point if it was assumed that its containing block held only the initial letter itself followed by an infinite sequence of plain text as the direct contents of its root inline box. Its position is not affected by line height inconsistencies introduced by the contents of the impacted line boxes.

Constant-sized text underlay shows how initial letter alignment
		          is not affected by the content of the spanned lines.

The initial letter does not increase the logical height of the line box in which it participates: it can protrude above or below it. It must be positioned such that its own block-start margin edge is below its containing block’s block-start content edge, and thus can force its originating line box (and subsequent content) to shift further away from that edge.

6.6.2. Inline Kerning

If the initial letter is a non-atomic inline with an automatic inline size and zero padding and borders, its margin box is kerned (negatively inset) by the distance from the start edge of its content box to the point in the content that would have been placed at the start edge of the line box if it were not an initial letter (i.e. the distance between its glyph bounding box and its start side bearing). This inset is effectively an additional inline-start margin on the box.

6.7. Initial Letter Wrapping: the initial-letter-wrap property

Note: initial-letter-wrap is at risk.

Name: initial-letter-wrap
Value: none | first | all | grid | <length-percentage>
Initial: none
Applies to: certain inline-level boxes and ::first-letter and inside ::marker boxes (see prose)
Inherited: yes
Percentages: relative to logical width of (last fragment of) initial letter
Computed value: specified keyword or computed <length-percentage> value
Canonical order: per grammar
Animation type: by computed value type

This property specifies whether lines impacted by an initial letter are shortened to fit the rectangular shape of the initial letter box or the contour of its glyph outline.

none
No contour-fitting is performed: each impacted line is aligned flush to the inline-end margin edge of the initial letter.
first
Behaves as none if the first typographic character unit after the initial letter belongs to Unicode General Category Zs. Otherwise behaves as for all on the first line of the block containing the initial letter and as none on the rest.
This example shows why contour-fitting the first line is necessary, and why it is dropped when the initial letter is followed by a space:
optical kerning in the presence or absence of a space after the initial letter
In the top paragraph, the initial letter "A" has a word space after it: the gap between the top of the "A" and the next letter provides the necessary word separation. In the next paragraph, the initial letter "A" is part of the first word, and leaving a gap between the top of the "A" and the next letter would create a jarring visual break within the word. In this case, the first line of text should be kerned into the initial letter’s area, as shown in the bottom paragraph.

Do we need an unconditional first? (I.e. Should we rename this value to auto and add a first value that does not check for spaces?) See GitHub issue 410

all
For each line of text impacted by the initial letter, the line box adjacent to the initial letter starts at the start-most point that does not overlap the initial letter’s glyph outline.

If the value of shape-outside is not none, shape-outside is used instead of the glyph outline.

In both cases, shape-margin is applied to expand the outline, and the resulting outline is clipped by the initial letter’s margin edges.

Note: This value is at-risk.

grid
This value is the same as none, except that the exclusion area of the impacted lines is increased as necessary for its end-edge to land on the character grid, i.e. to be a multiple of (1ic + letter-spacing) as computed on the containing block. The justify-self property can then be used to align the initial letter box within the exclusion area.
Diagram of Japanese initial letter in vertical writing mode
Diagram of Japanese initial letter in vertical writing mode

Note: In this example, the exclusion area for the drop initial is larger than its glyph in order to preserve inline-axis alignment.

Note: This value is also at-risk.

<length>
<percentage>
This value behaves the same as first except that the adjustment to the first line is given explicitly instead of being inferred from the glyph shape.

This really needs font-relative lengths to be relative to the used size.

Note: This value exists because it is easier to implement. Authors are encouraged to use the first value and to set margins to control spacing, and to use this as a fallback for glyph detection if necessary.

In the following example, UAs that support first will use the glyph outline plus the specified margin in order to place the first line, whereas UAs that only support <length> or <percentage> values will pull in the first line by 40% of the initial letter’s width (and then add the margin to that point).
h1 + p:first-letter {
  initial-letter: 3; /* 3-line drop-cap */
  initial-letter-wrap: first;
  margin-right: 0.1em;
}
@supports (not (initial-letter-wrap: first)) {
  /* Classes auto-generated on paragraphs to match first letter. */
  p.A:first-letter {
    initial-letter-wrap: -40%; /* Start of glyph outline, assuming correct font. */
  }
}

These values and related annoyance is likely unnecessary if someone submits a patch to Blink to support first.

Edit figure to show how auto behaves in varying contexts

p::first-letter {
  initial-letter: 3;
  initial-letter-wrap: none;
}
regular dropcap A
Ordinary initial letter with no wrapping.
p::first-letter {
  initial-letter: 3;
  initial-letter-wrap: all;
}

text wrapping around dropcap A

Text follows shape of initial letter. Each line box should just touch the ink of the letter, with some offset (represented by the shaded box).

p::first-letter {
  initial-letter: 3;
  initial-letter-wrap: first;
}

text wrapping around dropcap A but only on first line

Only the first line is moved up against the ink of the initial letter.

p::first-letter {
  initial-letter: 3;
  initial-letter-wrap: all;
}

text wrapping around dropcap V

text wrapping around dropcap P

text wrapping around dropcap W

6.8. Line Layout

An initial letter box is considered in-flow in its block formatting context, and is part of the contents of the line box in which it originates (its originating line box). Aside from the vertical axis (see § 6.6.1 Block-axis Positioning), its interaction with the rest of the contents of the line is as normal for inline-level content, except in a few specific details…

6.8.1. Inline Flow Layout: Alignment, Justification, and White Space

An initial letter box is handled similar to any other inline-level content participating in its originating line box, including participation in alignment, justification, and white space processing.

However, to ensure consistent alignment of all the impacted lines, collapsible white space between a sunken initial and subsequent content on its originating line is collapsed away, and any letter-spacing or justification opportunity that would normally be introduced by the juxtaposition of the contents of a sunken initial and the subsequent contents of the line is suppressed. (Note that this does not affect word-spacing or the justification opportunity introduced by a word separator because that space is provided by the typographic character unit alone and not by its juxtaposition with an adjacent character.)

6.8.2. Edge Effects: Indentation and Hanging Punctuation

text-indent and hanging-punctuation apply to an initial letter’s originating line box as usual, and cause a shift in the start of the line’s contents including the initial letter itself. Subsequent lines affected by the exclusion are shortened as usual, possibly more or less than otherwise depending on the resulting position of the initial letter.

initial letter with text indent
Initial letter with text indent.

The interaction of initial-letter and hanging-punctuation is under discussion.

6.8.3. Ancestor Inlines

If the initial letter box is contained by inline box ancestors, the boundaries of those inline boxes are drawn to exclude the initial letter box, as if it were outside their startmost margin edge. This is a purely geometric operation: it does not affect e.g. property inheritance or the effective letter-spacing between the initial letter box and subsequent content.

6.8.4. Multi-line Initial Letters

If an initial letter is too long to fit on one line, it wraps (according to the usual text-wrapping rules), each line filled and formatted exactly as if it were the first line and the initial letter too long to fit any subsequent normal text. Any normal text after the initial letter starts on its last line, affected exactly as if that line were the first line.

multi-line drop cap
Drop cap extends to two lines.

6.9. Clearing Initial Letters

6.9.1. Raised and sunken caps

The margin box of an initial letter contributes to the size of its containing element. Initial letters that extend above the first line of text, known as “raised caps” or “sunken caps,” do not extend up into previous elements. Since the content box for an initial letter includes all glyph ink, this also means that accents or other ink above the cap height of an initial letter will not impinge on previous elements.

raised cap para after normal para
Raised cap (initial-letter: 3 1) on right; note that the position of the “C” is the same in both cases, but on the right all text is moved down relative to the initial letter.

Handle glyph ink above cap height of font. Proposal: Make it an exclusion area for line boxes and border boxes. Include margin specified on initial-letters as part of exclusion area in order to control spacing.

Draw a box model diagram here. Does the margin of the initial letter collapse with its container?

6.9.2. Short paragraphs with initial letters

A paragraph with an initial letter can have fewer lines of text than the initial letter occupies. In this case, the initial letter’s top alignment is still honored, and its exclusion area continues into any subsequent blocks. This forces the subsequent inline-level content to wrap around the initial letter—exactly as if that block’s text were part of its own containing block. (This is similar to how floats exclude content in subsequent block boxes.)

short para with initial letter
The red text is a short paragraph with an initial letter. Note the subsequent paragraph wraps around the initial letter just as text in the paragraph with the initial letter does.

If the subsequent block starts with an initial letter, establishes an independent formatting context, or specifies clear in the initial letter’s containing block’s start direction, then it must clear the previous block’s initial letter.

short para with initial letter followed by para with initial
The red text is a short paragraph with an initial letter. The subsequent paragraph clears because it also has an initial letter.

6.9.3. Interaction with floats

Initial letters are not floats: they are in-flow inline-level content that belongs to a line box. Therefore:

initial letter interacting with floats
In the absence of an initial letter, the first line of text could abut the blue float. But the presence of the initial letter requires that the text move over.

See CSS2§9.5 for more information about the layout of floats and adjacent content. [CSS2]

Whether an inline-end float originating in subsequent lines must clear the initial letter (as inline-start floats do) is still under discussion. There is no aesthetic reason to require it; however it’s yet unclear how the underlying layout model would distinguish between the two cases.

6.9.4. Interaction with Fragmentation (Pagination)

Since a single glyph cannot be fragmented across pages (or columns or other fragmentation containers), an initial letter is considered monolithic [css-break-3] for the purpose of block-axis fragmentation (breaking across pages, columns, regions, etc.). Additionally, breaks between the in-flow lines alongside an initial letter box are avoided, much as breaks between line boxes affected be widows and orphans are avoided. However, if there is a forced break alongside the initial letter box, then it takes precedence; but has no effect on the initial letter box itself.

As with other monolithic objects, if an initial letter box occurs at the top of a fragmentation container and that fragmentation container is too short to contain it, it may be either truncated or sliced. Adjacent content, however, must be fragmented according to its own rules, not truncated or sliced along with the initial letter.

Appendix A: Synthesizing Alignment Metrics

A.1: Calculating Em-over and Em-under

Note: The em-over and em-under baselines are not used by CSS. Their definitions are included in this module for consistency with the other metrics used by Canvas TextMetrics API.

The em-over and em-under metrics are calculated as follows:

Note: This calculation ensures that em-over and em-under are always exactly 1em apart while trying to center the glyph outlines’ “center of gravity” between them.

A.2: Synthesizing Baselines (and Other Font Metrics) for Text

Some fonts might not contain the metrics information necessary to align text properly as described in this module. User agents may use the following strategies in the absence of a required metric:

Use related metrics
Certain metrics are typically related, and this relationship can be used to at least heuristically derive the missing metric. If the font format itself does not define any specific calculations, the following rules may be used:
  1. The central baseline is defined to be halfway between the ideographic-over and ideographic-under baselines, so any two of these determines the third.
  2. The ideographic-over and ideographic-under baselines are typically 1em apart, so if only one of the ideographic-over/ideographic-under/central baselines are provided, this relation can be used to calculate the other two.
  3. In CJK fonts the ascent and descent typically match the ideographic-over and ideographic-under baselines, so can be used as a fallback when both are missing.
Measure the font
Metrics may be derived from the glyph shapes. For example,
  1. The center of the minus sign (U+2212) can be taken as the mathematical baseline.
  2. The amount by which the lowercase “o” descends below the alphabetic baseline can be subtracted from its highest point to measure the x-height.
    measuring the x height of the letter o
    Measuring the x height.
  3. The amount by which the uppercase “O” descends below the alphabetic baseline can be subtracted from its highest point to measure the cap-height.
  4. The bounding box of 永 (U+6C38) can be used to find the ideographic character face edges.
  5. The top edge of the center of the Hebrew He (U+05D4 “ה”) can be taken as the Hebrew hanging baseline.
  6. The top edge of the center of the letter Ka can be taken as the hanging baseline. Which Ka is used should depend on the content language:
    Language Script Letter
    Devanagari क U+0915 KA
    Bengali ক U+0995
    Gurmukhi ਕ U+0A15
    Tibetan ཀ U+0F40

    Pick a default.

    finding the position of the hanging baseline of the letter ka
    The hanging baseline is at the top edge of the character ink.
  7. Issue: Add more notes here?

Somebody sanity-check these heuristics please.

Use fallback values
The following fallback values are suggested:
  • x-height: .5em;
  • cap-height: .66em;
  • hanging baseline: .6em;

A.3: Synthesizing Baselines for Atomic Inlines

If an atomic inline (such as an inline-block, inline-table, or replaced element) does not have a content-derived baseline set in the inline axis of the inline formatting context in which it participates, then the UA must synthesize its baselines as follows in order to align it.

These baselines are assumed to be at its line-under margin edge:

These baselines are assumed to be halfway between its line-under and line-over margin edges:

These baselines are assumed to be at its line-over margin edge:

Note: Authors can use margins (positive or negative) to adjust the alignment of replaced content within a line.

In this example, the author is using a set of images to display characters that don’t exist.
img[src^="/text/"] {
  height: 1em; /* Size to match adjacent text */
  margin-bottom: -0.2em; /* Baseline at 20% above bottom */
}
...
<p>This is some text with words written in an unencoded script:
<img src="/text/ch3439.png" alt="...">
  <img src="/text/ch3440.png" alt="...">
  <img src="/text/ch3442.png" alt="...">

Note: A future level of CSS may include a way of specifying a full baseline table for replaced elements. (This will probably look like a baseline-table property that accepts ''[<baseline-keyword> <percentage>]+''.)

Changes

Changes since the 14 November 2022 Working Draft:

Changes since the 28 August 2020 Working Draft:

Changes since the 18 June 2020 Working Draft include:

Changes since the 4 June 2020 Working Draft include:

Changes since the 8 August 2018 Working Draft include:

See also earlier changes since the 24 May 2016 Working Draft.

Acknowledgments

Special thanks goes to the initial authors, Eric A. Meyer and Michel Suignard.

In additions to the authors, this specification would not have been possible without the help from:

David Baron, Mike Bremford, David M Brown, Oriol Brufau, John Daggett, Stephen Deach, Sylvain Galineau, David Hyatt, Myles Maxfield, Shinyu Murakami, Jan Nicklas, Tess O’Connor, Sujal Parikh, Florian Rivoal, Alan Stearns, Weston Thayer, Bobby Tung, Chris Wilson, Grzegorz Zygmunt.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <strong class="advisement">, like this: UAs MUST provide an accessible alternative.

Conformance classes

Conformance to this specification is defined for three conformance classes:

style sheet
A CSS style sheet.
renderer
A UA that interprets the semantics of a style sheet and renders documents that use them.
authoring tool
A UA that writes a style sheet.

A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.

A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

Partial implementations

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported component values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

Implementations of Unstable and Proprietary Features

To avoid clashes with future stable CSS features, the CSSWG recommends following best practices for the implementation of unstable features and proprietary extensions to CSS.

Non-experimental implementations

Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at https://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSS-ALIGN-3]
Elika Etemad; Tab Atkins Jr.. CSS Box Alignment Module Level 3. 17 February 2023. WD. URL: https://www.w3.org/TR/css-align-3/
[CSS-BACKGROUNDS-3]
Bert Bos; Elika Etemad; Brad Kemper. CSS Backgrounds and Borders Module Level 3. 14 February 2023. CR. URL: https://www.w3.org/TR/css-backgrounds-3/
[CSS-BOX-4]
Elika Etemad. CSS Box Model Module Level 4. 3 November 2022. WD. URL: https://www.w3.org/TR/css-box-4/
[CSS-BREAK-3]
Rossen Atanassov; Elika Etemad. CSS Fragmentation Module Level 3. 4 December 2018. CR. URL: https://www.w3.org/TR/css-break-3/
[CSS-BREAK-4]
Rossen Atanassov; Elika Etemad. CSS Fragmentation Module Level 4. 18 December 2018. WD. URL: https://www.w3.org/TR/css-break-4/
[CSS-CASCADE-5]
Elika Etemad; Miriam Suzanne; Tab Atkins Jr.. CSS Cascading and Inheritance Level 5. 13 January 2022. CR. URL: https://www.w3.org/TR/css-cascade-5/
[CSS-COUNTER-STYLES-3]
Tab Atkins Jr.. CSS Counter Styles Level 3. 27 July 2021. CR. URL: https://www.w3.org/TR/css-counter-styles-3/
[CSS-DISPLAY-3]
Tab Atkins Jr.; Elika Etemad. CSS Display Module Level 3. 16 March 2023. CR. URL: https://www.w3.org/TR/css-display-3/
[CSS-FONTS-4]
John Daggett; Myles Maxfield; Chris Lilley. CSS Fonts Module Level 4. 21 December 2021. WD. URL: https://www.w3.org/TR/css-fonts-4/
[CSS-LISTS-3]
Elika Etemad; Tab Atkins Jr.. CSS Lists and Counters Module Level 3. 17 November 2020. WD. URL: https://www.w3.org/TR/css-lists-3/
[CSS-MULTICOL-1]
Florian Rivoal; Rachel Andrew. CSS Multi-column Layout Module Level 1. 12 October 2021. CR. URL: https://www.w3.org/TR/css-multicol-1/
[CSS-POSITION-3]
Elika Etemad; Tab Atkins Jr.. CSS Positioned Layout Module Level 3. 17 February 2023. WD. URL: https://www.w3.org/TR/css-position-3/
[CSS-PSEUDO-4]
Daniel Glazman; Elika Etemad; Alan Stearns. CSS Pseudo-Elements Module Level 4. 30 December 2022. WD. URL: https://www.w3.org/TR/css-pseudo-4/
[CSS-RUBY-1]
Elika Etemad; et al. CSS Ruby Annotation Layout Module Level 1. 31 December 2022. WD. URL: https://www.w3.org/TR/css-ruby-1/
[CSS-SHAPES-1]
Rossen Atanassov; Alan Stearns. CSS Shapes Module Level 1. 15 November 2022. CR. URL: https://www.w3.org/TR/css-shapes-1/
[CSS-SIZING-3]
Tab Atkins Jr.; Elika Etemad. CSS Box Sizing Module Level 3. 17 December 2021. WD. URL: https://www.w3.org/TR/css-sizing-3/
[CSS-TEXT-3]
Elika Etemad; Koji Ishii; Florian Rivoal. CSS Text Module Level 3. 13 February 2023. CR. URL: https://www.w3.org/TR/css-text-3/
[CSS-TEXT-4]
Elika Etemad; et al. CSS Text Module Level 4. 1 March 2023. WD. URL: https://www.w3.org/TR/css-text-4/
[CSS-UI-4]
Florian Rivoal. CSS Basic User Interface Module Level 4. 16 March 2021. WD. URL: https://www.w3.org/TR/css-ui-4/
[CSS-VALUES-3]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 3. 1 December 2022. CR. URL: https://www.w3.org/TR/css-values-3/
[CSS-VALUES-4]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 4. 19 October 2022. WD. URL: https://www.w3.org/TR/css-values-4/
[CSS-WRITING-MODES-4]
Elika Etemad; Koji Ishii. CSS Writing Modes Level 4. 30 July 2019. CR. URL: https://www.w3.org/TR/css-writing-modes-4/
[CSS2]
Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 7 June 2011. REC. URL: https://www.w3.org/TR/CSS21/
[CSS22]
Bert Bos. Cascading Style Sheets Level 2 Revision 2 (CSS 2.2) Specification. 12 April 2016. WD. URL: https://www.w3.org/TR/CSS22/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[I18N-GLOSSARY]
Richard Ishida; Addison Phillips. Internationalization Glossary. 11 February 2022. NOTE. URL: https://www.w3.org/TR/i18n-glossary/
[QUIRKS]
Simon Pieters. Quirks Mode Standard. Living Standard. URL: https://quirks.spec.whatwg.org/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[SVG2]
Amelia Bellamy-Royds; et al. Scalable Vector Graphics (SVG) 2. 4 October 2018. CR. URL: https://www.w3.org/TR/SVG2/

Informative References

[CSS-LINE-GRID-1]
Elika Etemad; Koji Ishii; Alan Stearns. CSS Line Grid Module Level 1. 16 September 2014. WD. URL: https://www.w3.org/TR/css-line-grid-1/
[CSS-WRITING-MODES-3]
Elika Etemad; Koji Ishii. CSS Writing Modes Level 3. 10 December 2019. REC. URL: https://www.w3.org/TR/css-writing-modes-3/
[ILREQ]
Swaran Lata. Indic Layout Requirements. 29 May 2020. WD. URL: https://www.w3.org/TR/ilreq/
[SELECT]
Tantek Çelik; et al. Selectors Level 3. 6 November 2018. REC. URL: https://www.w3.org/TR/selectors-3/

Property Index

Name Value Initial Applies to Inh. %ages Anim­ation type Canonical order Com­puted value
alignment-baseline baseline | text-bottom | alphabetic | ideographic | middle | central | mathematical | text-top baseline inline-level boxes, flex items, grid items, table cells, and SVG text content elements no N/A discrete per grammar specified keyword
baseline-shift <length-percentage> | sub | super | top | center | bottom 0 inline-level boxes and SVG text content elements no refer to the used value of line-height by computed value type per grammar the specified keyword or a computed <length-percentage> value
baseline-source auto | first | last auto inline-level boxes no N/A discrete per grammar specified keyword
dominant-baseline auto | text-bottom | alphabetic | ideographic | middle | central | mathematical | hanging | text-top auto block containers, inline boxes, table rows, grid containers, flex containers, and SVG text content elements yes N/A discrete per grammar specified keyword
initial-letter normal | <number [1,∞]> <integer [1,∞]> | <number [1,∞]> && [ drop | raise ]? normal certain inline-level boxes and ::first-letter and inside ::marker boxes (see prose) no N/A by computed value type per grammar the keyword normal or a number paired with an integer
initial-letter-align [ border-box? [ alphabetic | ideographic | hanging | leading ]? ]! alphabetic certain inline-level boxes and ::first-letter and inside ::marker boxes (see prose) yes N/A discrete per grammar specified keyword(s)
initial-letter-wrap none | first | all | grid | <length-percentage> none certain inline-level boxes and ::first-letter and inside ::marker boxes (see prose) yes relative to logical width of (last fragment of) initial letter by computed value type per grammar specified keyword or computed <length-percentage> value
inline-sizing normal | stretch normal inline boxes, but not ruby container boxes nor internal ruby boxes yes n/a discrete per grammar specified keyword
line-height normal | <number> | <length-percentage> normal non-replaced inline boxes and SVG text content elements yes computed relative to 1em by computed value type per grammar the specified keyword, a number, or a computed <length> value
text-box-edge leading | [ text | cap | ex | ideographic | ideographic-ink ] [ text | alphabetic | ideographic | ideographic-ink ]? leading inline boxes yes N/A discrete per grammar the specified keyword
text-box-trim none | start | end | both none block containers and inline boxes no N/A discrete per grammar the specified keyword
vertical-align [ first | last] || <'alignment-baseline'> || <'baseline-shift'> baseline see individual properties no N/A see individual properties per grammar see individual properties

Issues Index

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.
Define what to do for top/bottom/center aligned boxes that are taller than the rest of the content.
Firefox allows the inline boxes within an invisible 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.
The CSSWG would like to know which baseline values are necessary for each property that uses them (dominant-baseline, alignment-baseline, text-box-edge, initial-letter-align): if any can be dropped, or any need to be added. See Issue 859.
Define behavior for mixed vertical orientations that isn’t nonsensical when specified baseline isn’t central.
The line-relative shift values don’t fit perfectly in the dichotomy between alignment-baseline and baseline-shift. There’s decent arguments for either option. They’re currently drafted here, but if there’s a strong argument to move them, please file an issue for consideration.
We would prefer to remove the baseline value, and are looking for feedback from SVG user agents as to whether it’s necessary.
The fact that percentages compute to lengths is annoying. See also Issue 3118 and Issue 2165.
This is an early draft of a proposal, and might change significantly as design critiques and use cases are registered and various details and interactions with other properties are worked out. Do not implement (yet).
Do we need longhands or is this shorthand enough? [Issue #5236]
This is an early draft of a proposal, and is likely to change significantly as design critiques and use cases are registered. Values and property names may be added, dropped, and/or renamed, and the overall syntax or behavior may change, particularly in response to authoring and robustness considerations for handling descendant boxes. Do not implement (yet).
Should inline boxes automatically do this? And/or is it better for line sizing and content-box sizing to be separably controlled?
This has a confusing name. We need a new name. [Issue #5189]
The editors would appreciate any examples of drop initials in non-western scripts, especially Indic scripts.
Should there be a way to opt out of this behavior? See GitHub Issue 310.
Correct alignment of initial letter in scripts such as Hebrew and Thai is currently not possible because OpenType lacks corresponding metrics. (Issue 5244)
Hebrew 2-line drop-letter alignment using the hebrew-top and alphabetic baselines
This only covers the most common cross-linguistic transcription systems. Should we include any other / all script tags in the UA style sheet?
What about inheritance to descendants? [Issue #4988]
Update this calculation to be a) generic across writing systems / alignment points and b) handle non-integer sizes.
Should the hanging punctuation be included in the box instead (so that the box is drawn around the punctuation when it is made visible through borders/background), but rather only excluded when positioning the box (so that the initial letter remains flush, with the hanging punctuation properly hanging)? See discussion.
Do we need an unconditional first? (I.e. Should we rename this value to auto and add a first value that does not check for spaces?) See GitHub issue 410
This really needs font-relative lengths to be relative to the used size.
These values and related annoyance is likely unnecessary if someone submits a patch to Blink to support first.
Edit figure to show how auto behaves in varying contexts
The interaction of initial-letter and hanging-punctuation is under discussion.
Handle glyph ink above cap height of font. Proposal: Make it an exclusion area for line boxes and border boxes. Include margin specified on initial-letters as part of exclusion area in order to control spacing.
Draw a box model diagram here. Does the margin of the initial letter collapse with its container?
Whether an inline-end float originating in subsequent lines must clear the initial letter (as inline-start floats do) is still under discussion. There is no aesthetic reason to require it; however it’s yet unclear how the underlying layout model would distinguish between the two cases.
Pick a default.
Somebody sanity-check these heuristics please.