CSS Display Module Level 4

1. Introduction

This section is normative.

CSS takes a source document organized as a tree of elements (which can contain a mix of other elements and text nodes) and text nodes (which can contain text), and renders it onto a canvas such as your screen, a piece of paper, or an audio stream. Although any such source document can be rendered with CSS, the most commonly used type is the DOM. [DOM] (Some of these more complex tree types might have additional types of nodes, such as the comment nodes in the DOM. For the purposes of CSS, all of these additional types of nodes are ignored, as if they didn’t exist.)

To do this, it generates an intermediary structure, the box tree, which represents the formatting structure of the rendered document. Each box in the box tree represents its corresponding element (or pseudo-element) in space and/or time on the canvas, while each text sequence in the box tree likewise represents the corresponding contents of its text nodes.

To create the box tree, CSS first uses cascading and inheritance, to assign a computed value for each CSS property to each element and text node in the source tree. (See [CSS-CASCADE-3].)

Then, for each element, CSS generates zero or more boxes as specified by that element’s display property. Typically, an element generates a single box, the principal box, which represents itself and contains its contents in the box tree. However, some display values (e.g. display: list-item) generate more than one box (e.g. a principal block box and a child marker box). And some values (such as none or contents) cause the element and/or its descendants to not generate any boxes at all. Boxes are often referred to by their display type—​e.g. a box generated by an element with display: block is called a “block box” or just a “block”.

A box is assigned the same styles as its generating element, unless otherwise indicated. In general, inherited properties are assigned to the principal box, and then inherit through the box tree to any other boxes generated by the same element. Non-inherited properties default to applying to the principal box, but when the element generates multiple boxes, are sometimes defined to apply to a different box: for example, the border properties applied to a table element are applied to its table grid box, not to its principal table wrapper box. If the value computation process alters the styles of those boxes, and the element’s style is requested (such as through getComputedStyle()), the element reflects, for each property, the value from the box to which that property was applied.

Similarly, each contiguous sequence of sibling text nodes generates a text sequence containing their text contents, which is assigned the same styles as the generating text nodes. If the sequence contains no text, however, it does not generate a text sequence.

In constructing the box tree, boxes generated by an element are descendants of the principal box of any ancestor elements. In the general case, the direct parent box of an element’s principal box is the principal box of its nearest ancestor element that generates a box; however, there are some exceptions, such as for run-in boxes, display types (like tables) that generate multiple container boxes, and intervening anonymous boxes.

An anonymous box is a box that is not associated with any element. Anonymous boxes are generated in certain circumstances to fix up the box tree when it requires a particular nested structure that is not provided by the boxes generated from the element tree. For example, a table cell box requires a particular type of parent box (the table row box), and will generate an anonymous table row box around itself if its parent is not a table row box. (See [CSS2] § 17.2.1.) Unlike element-generated boxes, whose styles inherit strictly through the element tree, anonymous boxes (which only exist in the box tree) inherit through their box tree parentage.

In the course of layout, boxes and text sequences can be broken into multiple fragments. This happens, for example, when an inline box and/or text sequence is broken across lines, or when a block box is broken across pages or columns, in a process called fragmentation. It can also happen due to bidi reordering of text (see Applying the Bidirectional Reordering Algorithm in CSS Writing Modes) or higher-level display type box splitting, e.g. block-in-inline splitting (see CSS2§9.2) or column-spanner-in-block splitting (see CSS Multi-column Layout). A box therefore consists of one or more box fragments, and a text sequence consists of one or more text fragments. See [CSS-BREAK-3] for more information on fragmentation.

Note: Many of the CSS specs were written before this terminology was ironed out, or refer to things incorrectly, so view older specs with caution when they’re using these terms. It should be possible to infer from context which term they really mean. Please report errors in specs when you find them, so they can be corrected.

Note: Further information on the “aural” box tree and its interaction with the display property can be found in the CSS Speech Module. [CSS-SPEECH-1]

1.1. Module interactions

This module replaces and extends the definition of the display property defined in [CSS2] section 9.2.4.

None of the properties in this module apply to the ::first-line or ::first-letter pseudo-elements.

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. Box Layout Modes: the display property

User agents are expected to support this property on all media, including non-visual ones. The display property defines an element’s display type, which consists of the two basic qualities of how an element generates boxes:

• the inner display type, which defines (if it is a non-replaced element) the kind of formatting context it generates, dictating how its descendant boxes are laid out. (The inner display of a replaced element is outside the scope of CSS.)

• the outer display type, which dictates how the principal box itself participates in flow layout.

Text sequences have no display type.

Some display values have additional side-effects: such as list-item, which also generates a ::marker pseudo-element, and none, which causes the element’s entire subtree to be left out of the box tree.

Values are defined as follows:

<display-outside>  = block | inline | run-in
<display-inside>   = flow | flow-root | table | flex | grid | ruby
<display-listitem> = <display-outside>? && [ flow | flow-root ]? && list-item
<display-internal> = table-row-group | table-header-group |
           table-footer-group | table-row | table-cell |
           table-column-group | table-column | table-caption |
           ruby-base | ruby-text | ruby-base-container |
           ruby-text-container
<display-box>      = contents | none
<display-legacy>   = inline-block | inline-table | inline-flex | inline-grid

The following informative table summarizes the values of display:

Note: Following the precedence rules of “most backwards-compatible, then shortest”, serialization of equivalent display values uses the “Short display” column. [CSSOM]

2.1. Outer Display Roles for Flow Layout: the block, inline, and run-in keywords

The <display-outside> keywords specify the element’s outer display type, which is essentially its principal box’s role in flow layout. They are defined as follows:

block

The element generates a box that is block-level when placed in flow layout. [CSS2]

inline

The element generates a box that is inline-level when placed in flow layout. [CSS2]

run-in

The element generates an run-in box, which is a type of inline-level box with special behavior that attempts to merge it into a subsequent block container. See § 6 Run-In Layout for details.

Note: Outer display types do affect replaced elements.

If a <display-outside> value is specified but <display-inside> is omitted, the element’s inner display type defaults to flow.

2.2. Inner Display Layout Models: the flow, flow-root, table, flex, grid, and ruby keywords

The <display-inside> keywords specify the element’s inner display type, which defines the type of formatting context that lays out its contents (assuming it is a non-replaced element). They are defined as follows:

flow

The element lays out its contents using flow layout (block-and-inline layout).

If its outer display type is inline or run-in, and it is participating in a block or inline formatting context, then it generates an inline box.

Otherwise it generates a block container box.

Depending on the value of other properties (such as position, float, or overflow) and whether it is itself participating in a block or inline formatting context, it either establishes a new block formatting context for its contents or integrates its contents into its parent formatting context. See CSS2.1 Chapter 9. [CSS2] A block container that establishes a new block formatting context is considered to have a used inner display type of flow-root.

flow-root

The element generates a block container box, and lays out its contents using flow layout. It always establishes a new block formatting context for its contents. [CSS2]

table

The element generates a principal table wrapper box that establishes a block formatting context, and which contains an additionally-generated table grid box that establishes a table formatting context. [CSS2]

flex

The element generates a principal flex container box and establishes a flex formatting context. [CSS-FLEXBOX-1]

grid

The element generates a principal grid container box, and establishes a grid formatting context. [CSS-GRID-1]

(Grids using subgrid might not generate a new grid formatting context; see [CSS-GRID-2] for details.)

ruby

The element generates a ruby container box and establishes a ruby formatting context in addition to integrating its base-level contents into its parent formatting context (if it is inline) or generating a wrapper box of the appropriate outer display type (if it is not). [CSS-RUBY-1]

If a <display-inside> value is specified but <display-outside> is omitted, the element’s outer display type defaults to block—​except for ruby, which defaults to inline.

2.3. Generating Marker Boxes: the list-item keyword

The list-item keyword causes the element to generate a ::marker pseudo-element [CSS-PSEUDO-4] with the content specified by its list-style properties (CSS 2.1§12.5 Lists) [CSS2] together with a principal box of the specified type for its own contents.

If no inner display type value is specified, the principal box’s inner display type defaults to flow. If no outer display type value is specified, the principal box’s outer display type defaults to block.

Note: In this level, as restricted in the grammar, list-items are limited to the Flow Layout display types (block/inline/run-in with flow/flow-root inner types). This restriction may be relaxed in a future level of this module.

2.4. Layout-Internal Display Types: the table-* and ruby-* keywords

Some layout models, such as table and ruby, have a complex internal structure, with several different roles that their children and descendants can fill. This section defines those “layout-internal” display values, which only have me