CSS Display Module Level 3

1. Introduction

This section is normative.

CSS takes a source document, organized as a tree of elements, and renders it onto a canvas (such as your screen, a piece of paper, or an audio stream). To do this, it generates an intermediary structure, the box tree, which represents the formatting structure of the rendered document. Each box represents its corresponding element (or pseudo-element) in space and/or time on the canvas.

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

Then, for each element, it generates zero or more boxes as specified by that element’s display property. Typically, an element generates a single box. However, some display values (e.g. display: list-item) generate more than one box (e.g. a principal block box and a 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 assigned the same styles as their generating element, unless otherwise indicated. They’re 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”.

An anonymous box is 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, a box may be broken into multiple fragments. This happens, for example, when an inline box is broken across lines, or when a block box is broken across pages or columns. A box therefore consists of one or more box fragments. See [CSS3-BREAK] 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. [CSS3-SPEECH]

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

This specification follows the CSS property definition conventions from [CSS2].

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 it has not been repeated explicitly.

2. Box Layout Modes: the display property

The display property defines box’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 box participates in its parent formatting context.

Some display values have additional side-effects, such as:

• flow-root, which makes the element become a formatting context.

• list-item, which also generates a ::marker pseudo-element.

• none, which causes the element’s entire subtree to be left out of the box tree.

Values are defined as follows:

<display-outside>  = block-level | inline-level | run-in ;
<display-inside>   = auto | block | table | flex | grid | ruby ;
<display-normal>   = <display-outside> || <display-inside> || flow-root ;
<display-listitem> = list-item && <display-outside>? && [ auto | block ]? && flow-root? ;
<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 | inline-block | inline-list-item |
                     inline-table | inline-flex | inline-grid ;

The computed value is obtained from the following algorithm, after the display types have been modified by a possible blockification or inlinification, and after converting an auto inner display type to block when the outer display type is block-level.

• The computed value is the specified value in case of none or contents.

• Otherwise, if all the following conditions hold, it’s the equivalent precomposed inline-level display value.

  • The outer display type is inline-level.

  • The inner display type is not ruby.

  • The inner display type is auto or the list-item keyword was not specified.

  • The flow-root keyword was not specified.

• Otherwise, it is the concatenation of:

  • The list-item keyword, if specified.

  • The outer display type, if none of the following holds:

    • It is block-level and the inner display type is not auto nor ruby.

    • It is inline-level and the inner display type is ruby.

  • The inner display type, if none of the following holds:

    • It is auto.

    • The outer display type is layout-internal.

  • The flow-root keyword, if specified.

The following informative table summarizes the basic 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-level, inline-level, and run-in keywords

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

block-level

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

inline-level

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

run-in

The element generates a run-in box when placed in flow layout. Run-in elements act like inlines or blocks, depending on the surrounding elements. See §3 Run-In Layout for details.

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

If the element has an inner display type that generates multiple boxes, such as table or ruby, the outer display type applies to the principal box.

2.2. Inner Display Layout Models: the auto, block, 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:

auto

If (after inlinifying or blockifying, when applicable) the element’s outer display type is block-level, then auto is changed to block, and display computes accordingly.

Otherwise, the element generates an inline box.

block

The element generates a block container box, and lays out its contents using flow layout.

Depending on the outer display type, the value of other properties (such as position, float, or overflow) and whether it is itself participating in a block formatting context, the element 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]

table

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

flex

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

grid

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

ruby

The element generates a principal auto container box, which contains an additionally-generated inline-level ruby container that establishes a ruby formatting context in addition to integrating its base-level contents into its parent formatting context. [CSS3RUBY]

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

2.3. Becoming a formatting context: the flow-root keyword

The flow-root keyword causes the element to become a formatting context. If the element’s inner display type is table, flex, grid, this condition is satisfied. Otherwise, if the element’s inner display type is auto, block or ruby, the principal box becomes a block container which establishes a BFC. This change does not affect the computed value of the display property.

If the flow-root keyword is specified and both <display-outside> and <display-inside> are omitted, the element’s outer display type defaults to block-level. If only one display type is ommitted, it defaults as usual.

In some circumstances, an element may become a formatting context by other means than the flow-root keyword (see [CSS-CONTAIN-1] or [CSS3-MULTICOL] for examples).

Note: the flow-root keyword usually has no effect on an inline-block, because it already establishes a BFC. But if that box is blockified, with flow-root the resulting block box will continue establishing a BFC. Without flow-root, it might integrate its contents into its parent BFC instead.

How should an element with a layout-internal inner display type behave when becoming a formatting context?

Should the flow-root keyword be allowed in <display-internal>? It might be useful in case the element is blockified.

2.4. Generating Marker Boxes: the list-item keyword

The list-item keyword causes the element to generate a ::marker pseudo-element box [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 the list-item keyword is specified and both <display-outside> and <display-inside> are omitted, the element’s outer display type defaults to block-level. If only one display type is ommitted, it defaults as usual.

Note: In this level, as restricted in the grammar, a list-item can only be a block box, a block formatting context root box, an inline box, or an inline-block box. This restriction may be relaxed in a future level of this module.

2.5. 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 meaning within that particular layout mode.

Unless otherwise specified, both the inner display type and the outer display type of elements using these display values are set to the given keyword.

The <display-internal> keywords are defined as follows:

table-row-group, table-header-group, table-footer-group, table-row, table-cell, table-column-group, table-column

The element is an internal table element. It generates the appropriate internal table box which participates in a table formatting context. See CSS2§17.2 [CSS2].

table-cell boxes have a block inner display type.

table-caption

The element generates a table caption box, which is a block box with special behavior with respect to table and table wrapper boxes. See CSS2§17.2 [CSS2].

table-caption boxes have a block inner display type.

ruby-base, ruby-text, ruby-base-container, ruby-text-container

The element is an internal ruby element. It generates the appropriate internal ruby box which participates in a ruby formatting context. [CSS3RUBY]

ruby-base and ruby-text have an auto inner display type.

Boxes with layout-specific display types generate anonymous wrapper boxes around themselves when placed in an incompatible parent, as defined by their respective specifications.

<div style="display:block;">
  <div style="display:table-cell">...</div>
</div>

block box
└anonymous table box
 └anonymous table-row-group box
  └anonymous table-row box
   └table-cell box

<div style="display:table;">
  <div style="display:table-row">
    <div style="display:table-cell">...</div>
  </div>
</div>

table box
└anonymous table-row-group box
 └table-row box
  └table-cell box

2.6. Box Generation: the none and contents keywords

While display can control the types of boxes an element will generate, it can also control whether an element will generate any boxes at all.

The <display-box> keywords are defined as follows:

contents

The element itself does not generate any boxes, but its children and pseudo-elements still generate boxes as normal. For the purposes of box generation and layout, the element must be treated as if it had been replaced in the element tree by its contents (including both its source-document children and its pseudo-elements, such as ::before and ::after pseudo-elements, which are generated before/after the element’s children as normal).

Note: As only the box tree is affected, any semantics based on the document tree, such as selector-matching and event handling, are not affected.

This value behaves as display: none on replaced elements and other elements whose rendering is not entirely controlled by CSS; see Appendix B: Effects of display: contents on Unusual Elements for details.

Note: Replaced elements and form controls are treated specially because removing only the element’s own generating box is a more-or-less undefined operation. As this behavior may be refined if use cases (and more precise rendering models) develop, authors should use display: none rather than display: contents on such elements for forward-compatibility.

none

The element and its descendants generate no boxes.

Elements with either of these values do not have inner or outer display types, because they don’t generate any boxes at all.

Note: As these values cause affected elements to not generate a box, anonymous box generation rules will ignore the elided elements entirely, as if they did not exist in the box tree.

Markup-based relationships, however, are not affected by these values, as they are solely rendering-time effects. For example, although they may affect which table cell appears in a column, they do not affect which table cell is associated with a particular column element. Similarly, they cannot affect which HTML summary element is associated with a particular table or whether a legend is the name of a fieldset.

2.7. Precomposed Inline-level Display Values

CSS level 2 used a single-keyword syntax for display, requiring separate keywords for block-level and inline-level variants of the same layout mode. These <display-legacy> keywords map as follows:

inline

Behaves as inline-level.

inline-block

Behaves as inline-level block.

inline-table

Behaves as inline-level table.

inline-flex

Behaves as inline-level flex.

inline-grid

Behaves as inline-level grid.

inline-list-item

Behaves as inline-level list-item.

2.8. Automatic Box Type Transformations

Some layout effects require blockification or inlinification of the box type, which sets the box’s outer display type to block-level or inline-level (respectively). (This has no effects on display types that generate no box at all, such as none or contents.)

If an inline-level auto box is inlinified, it recursively inlinifies all of its in-flow children, so that no block-level descendants break up the inline formatting context in which it participates.

If a layout-internal box is blockified, its inner display type converts to auto so that it becomes a block container.

Should conversion of layout-internal display types also happen for inlinification? If it does, should it change to auto or block? If it doesn’t, then anonymous-box fixup will handle things.

The root element’s display type is always blockified. Additionally, a display of contents computes to block on the root element.

3. Run-In Layout

A run-in box is a box that merges into a block that comes after it, inserting itself at the beginning of that block’s inline-level content. This is useful for formatting compact headlines, definitions, and other similar things, where the appropriate DOM structure is to have a headline preceding the following prose, but the desired display is an inline headline laying out with the text.

<dl class='dict'>
  <dt>dictionary
  <dd>a book that lists the words of a language in alphabetical
      order and gives their meaning, or that gives the equivalent
      words in a different language.
  <dt>glossary
  <dd>an alphabetical list of terms or words found in or relating
      to a specific subject, text, or dialect, with explanations; a
      brief dictionary.
</dl>
<style>
.dict > dt {
  display: run-in;
}
.dict > dt::after {
  content: ": "
}
</style>

dictionary: a book that lists the words of a language
in alphabetical order and explains their meaning.

glossary: an alphabetical list of terms or words found
in or relating to a specific subject, text, or dialect,
with explanations; a brief dictionary.

A run-in box behaves exactly as an inline-level box, except:

• If a run-in sequence is immediately followed by a block box that does not establish a new block formatting context, it is inserted as direct children of the block box after its ::marker pseudo-element’s boxes (if any), but preceding any other boxes generated by the contents of the block (including the box generated by the ::before pseudo-element, if any).

  The reparented content is then formatted as if originally parented there. Note that only layout is affected, not inheritance, because property inheritance for non-anonymous boxes is based only on the element tree.

• Otherwise, an anonymous block box is generated around the run-in sequence and all immediately following inline-level content (up to, but not including, the next run-in sequence, if any).
• A run-in box with an auto inner display type inlinifies its contents.

A run-in sequence is a maximal sequence of consecutive sibling run-in boxes and intervening white space and/or out-of-flow boxes.

Note: This statement implies that out-of-flow boxes are reparented if they are between two run-in boxes. Another alternative would be to leave behind the intervening out-of-flow boxes, or to have out-of-flow boxes impede the running-in of earlier boxes. Implementers and authors are encouraged to contact the CSSWG if they have a preferred behavior, as this one was picked somewhat at random.

Note: As the earliest run-in represents the first text on the first formatted line of its containing block, a ::first-letter pseudo-element applied to that block element selects the first letter of the run-in, rather than the first letter of its own contents.

Note: This run-in model is slightly different from the one proposed in earlier revisions of [CSS2].

Appendix A: Glossary

The following terms are defined here for convenience:

principal box

When an element generates one or more boxes, one of them is the principal box, which contains its descendant boxes and generated content, and is also the box involved in any positioning scheme.

Some elements may generate additional boxes in addition to the principal box (such as list-item elements, which generate an additional marker box, or table elements, which generate a principal table wrapper box and an additional table box. These additional boxes are placed with respect to the principal box.

inline-level

Content that participates in inline layout. Specifically, inline-level boxes and text.

block-level

Content that participates in block layout. Specifically, block-level boxes.

inline box

A non-replaced inline-level box whose inner display type is auto. The contents of an inline box participate in the same inline formatting context as the inline box itself.

inline

Used as a shorthand for inline box or inline-level box where unambiguous, or as an adjective meaning inline-level. The latter usage is deprecated.

atomic inline

An inline-level box that is replaced (such as an image) or that establishes a new formatting context (such as an inline-block or inline-table) and cannot split across lines (as inline boxes and ruby containers can).

Any inline-level box whose inner display type is not auto establishes a new formatting context of the specified inner display type.

block container

A block container either contains only inline-level boxes participating in an inline formatting context, or contains only block-level boxes participating in a block formatting context (possibly generating anonymous block boxes to ensure this constraint, as defined in CSS2§9.2.1.1).

A block container that contains only inline-level content establishes a new inline formatting context. The element then also generates a root inline box which wraps all of its inline content. Note, this root inline box concept effectively replaces the "anonymous inline element" concept introduced in CSS2§9.2.2.1.

A block container that contains only block-level boxes establishes a new block formatting context if its parent formatting context is not a block formatting context; otherwise, when participating in a block formatting context itself, it either establishes a new block formatting context for its contents or continues the one in which it participates, as determined by the constraints of other properties (such as overflow or align-content).

Note: Not all block container boxes are block-level boxes: non-replaced inline blocks and non-replaced table cells are block containers but not block-level boxes. Block-level boxes that are also block containers are called block boxes.

block box

A block-level box that is also a block container.

block

Used as a shorthand for block box, block-level box, or block container box, where unambiguous.

replaced element

An element whose content is outside the scope of the CSS formatting model, such as an image, embedded document, or applet. For example, the content of the HTML img element is often replaced by the image that its src attribute designates. Replaced elements often have intrinsic dimensions: an intrinsic width, an intrinsic height, and an intrinsic ratio. For example, a bitmap image has an intrinsic width and an intrinsic height specified in absolute units (from which the intrinsic ratio can obviously be determined). On the other hand, other documents may not have any intrinsic dimensions (for example, a blank HTML document).

User agents may consider a replaced element to not have any intrinsic dimensions if it is believed that those dimensions could leak sensitive information to a third party. For example, if an HTML document changed intrinsic size depending on the user’s bank balance, then the UA might want to act as if that resource had no intrinsic dimensions.

The content of replaced elements is not considered in the CSS rendering model.

containing block

A rectangle that forms the basis of sizing and positioning for the boxes associated with it (usually the children of the box that generated it). Notably, a containing block is not a box (it is a rectangle), however it is often derived from the dimensions of a box. If properties of a containing block are referenced, they reference the values on the box that generated the containing block. (For the initial containing block, the values are taken from the root element.) See [CSS2] Section 9.1.2 and Section 10.1 for details.

containing block chain

A sequence of successive containing blocks that form an ancestor-descendant chain through the containing block relation. For example, an inline box’s containing block is the content box of its closest block container ancestor; if that block container is an in-flow block, then its containing block is formed by its parent block container; if that grandparent block container is absolutely positioned, then its containing block is the padding edges of its closest positioned ancestor (not necessarily its parent), and so on up to the initial containing block.

initial containing block

The containing block of the root element. See CSS2.1§10.1 for continuous media; and [CSS3PAGE] for paged media.

formatting context

A formatting context is the environment into which a set of related boxes are laid out. Different formatting contexts lay out their boxes according to different rules. For example, a flex formatting context lays out boxes according to the flex layout rules [CSS3-FLEXBOX], whereas a block formatting context lays out boxes according to the block-and-inline layout rules [CSS2].

When a box establishes a new formatting context (whether that formatting context is of the same type as its parent or not), it essentially creates a new, independent layout environment: except through the sizing of the box itself, the layout of its descendants is (generally) not affected by the the rules and contents of the formatting context outside the box, and vice versa.

For example, in a block formatting context, floated boxes affect the layout of surrounding boxes. But their effects do not escape their formatting context: the box establishing their formatting context grows to fully contain them, and floats from outside that box are not allowed to protrude into and affect the contents inside the box.

As another example, margins do not collapse across formatting context boundaries.

Exclusions are able to affect content across formatting context boundaries. (At time of writing, they are the only layout feature that can.) [CSS3-EXCLUSIONS]

block formatting context

inline formatting context

Block and inline formatting contexts are defined in CSS 2.1 Section 9.4.

BFC

Informal abbreviation for block formatting context. Often used to refer to a block formatting context root, that is, a block box that establishes a new block formatting context for its contents.

out-of-flow

in-flow

A box is out-of-flow if it is floated (via float) or absolutely-positioned (via absolute or fixed positioning). A box is in-flow if it is not out-of-flow.

Note: some formatting contexts inhibit floating, so that an element with float: left is not necessarily out-of-flow.

See [CSS2] Chapter 9 for a fuller definition of these terms.

Appendix B: Effects of display: contents on Unusual Elements

This section is (currently) non-normative.

Some elements aren’t rendered purely by CSS box concepts; for example, replaced elements (such as img), many form controls (such as input), and SVG elements.

This appendix defines how they interact with display: contents.

HTML Elements

br

wbr

meter

progress

applet

canvas

embed

object

audio

iframe

img

video

frame

frameset

input

textarea

select

display: contents behaves as display: none.

legend

Per HTML, a legend with display: contents is not a rendered legend, so it does not have magical display behavior. (Thus, it reacts to display: contents normally.)

button

details

fieldset

These elements don’t have any special behavior; display: contents simply removes their principal box, and their contents render as normal.

any other HTML element

Behaves as normal for display: contents.

SVG Elements

Root svg

display: contents behaves as display: none.

Nested svg

g

use (treated as a Shadow DOM container)

tspan

display: contents strips the element from the formatting tree, and hoists its contents up to display in its place.

any other SVG elements

display: contents behaves as display: none.

Acknowledgments

We would like to thank the many people who have attempted to separate out the disparate details of box generation over the years, most particularly Bert Bos, whose last attempt with display-model and display-role didn’t get anywhere, but primed us for the current spec, and Anton Prowse, whose relentless assault on CSS2.1 Chapter 9 forced some order out of the chaos.

Changes

Changes since the ??? Working Draft include:

• Deferred the box-suppress/display-or-not property to the next level of Display, in order to provide time for futher discussion of use cases.
• Specified that display: contents computes to display: inline on replaced elements and form controls.
• Clarified that an element’s ::before and ::after pseudo-elements still exist if its own box is not generated due to display: contents.
• Clarified that event bubbling is not affected by display: contents.
• Clarified interaction of run-ins with out-of-flow elements and ::first-letter.
• Switched table-caption and table-cell to use flow-root as their inner display type, since they always form a formatting context root.
• Closed off remaining issues and added at-risk list.
• Added the definition of becoming a formatting context

Changes since the 21 July 2015 Working Draft include:

• Added definitions for in-flow and out-of-flow to glossary.

Changes since the 11 September 2014 Working Draft include:

• Removed display-inside, display-outside, and display-extras longhands, in favor of just making display multi-value. (This was done to impose constraints on what can be combined. Future levels of this specification may relax some or all of those restrictions if they become unnecessary or unwanted.)
• Created the flow and flow-root inner display types to better express flow layout display types and to create an explicit switch for making an element a BFC root. (This should eliminate the need for hacks like ::after { clear: both; } and overflow: hidden that are intended to accomplish this purpose.)

4. Privacy and Security Considerations

This specification introduces no new privacy or security considerations.