CSS Display Module Level 3

W3C Working Draft,

This version:
Latest published version:
Editor's Draft:
Previous Versions:
Tab Atkins Jr. (Google)
Elika J. Etemad / fantasai (Invited Expert)
Issue Tracking:
GitHub Issues


This module describes how the CSS formatting box tree is generated from the document element tree and defines the display property that controls it.

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

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. 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/.

Publication as a Working Draft does not imply endorsement by the W3C Membership. 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.

GitHub Issues are preferred for discussion of this specification. When filing an issue, please put the text “css-display” in the title, preferably like this: “[css-display] …summary of comment…”. All issues and comments are archived, and there is also a historical archive.

This document was produced by the CSS Working Group (part of the Style Activity).

This document was produced by a group operating under the 5 February 2004 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.

This document is governed by the 1 September 2015 W3C Process Document.

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

Name: display
Value: [ <display-outside> || <display-inside> ] | <display-listitem> | <display-internal> | <display-box> | <display-legacy>
Initial: inline
Applies to: all elements
Inherited: no
Percentages: n/a
Media: all
Computed value: as specified
Canonical order: per grammar
Animatable: no

The display property defines box’s display type, which consists of the two basic qualities of how an element generates boxes:

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> = list-item && <display-outside>? && [ flow | 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-block | inline-list-item |
                     inline-table | inline-flex | inline-grid ;

The following informative table summarizes the values of display:

Short display Full display Generated box
none subtree omitted from box tree
contents element replaced by contents in box tree
block block flow block-level block container aka block box
flow-root block flow-root block-level block container that establishes a new block formatting context (BFC)
inline inline flow inline box
inline-block inline flow-root inline-level block container
run-in run-in flow run-in box (inline box with special box-tree-munging rules)
list-item list-item block flow block box with additional marker box
inline-list-item list-item inline flow inline box with additional marker box
flex block flex block-level flex container
inline-flex inline flex inline-level flex container
grid block grid block-level grid container
inline-grid inline grid inline-level grid container
ruby inline ruby inline-level ruby container
block ruby block ruby block box containing ruby container
table block table block-level table wrapper box containing table box
inline-table inline table inline-level table wrapper box containing table box
table-cell table-cell flow-root table cell block container
table-caption table-caption flow-root table cell block container
ruby-base ruby-base flow layout-specific internal box
ruby-text ruby-text flow layout-specific internal box
other <display-internal> layout-specific internal box

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 role in flow layout. They are defined as follows:

The element generates a block-level box. [CSS2]
The element generates an inline-level box. [CSS2]
The element generates a run-in box. 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 flow.

2.2. Inner Display Layout Models: the flow, flow-root, table, 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:

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]

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]
The element generates a principal table wrapper box containing an additionally-generated table box, and establishes a table formatting context. [CSS2]
The element generates a principal flex container box and establishes a flex formatting context. [CSS3-FLEXBOX]
The element generates a principal grid container box, and establishes a grid formatting context. [CSS3-GRID-LAYOUT]
The element generates a principal ruby container box, and establishes a ruby formatting context. [CSS3RUBY]

If a <display-inside> value is specified but <display-outside> is omitted, the element’s outer display type defaults to blockexcept 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 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 no <display-inside> value is specified, the principal box’s inner display type defaults to flow. If no <display-outside> value is specified, the principal box’s outer display type defaults to block.

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.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 "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, table-caption
The element is an internal table element, and participates in a table layout context. [CSS2]

table-cell and table-caption have a flow-root inner display type.

ruby-base, ruby-text, ruby-base-container, ruby-text-container
The element is an internal ruby element, and participates in a ruby layout context. [CSS3RUBY]

ruby-base and ruby-text have a flow 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.

For example, Table Layout requires that a table-cell box must have a table-row parent box.

If it is misparented, like so:

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

It will generate wrapper boxes around itself, producing a structure like:

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

Even if the parent is another internal table element, if it’s not the correct one, wrapper boxes will be generated. For example, in the following markup:

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

Anonymous wrapper box generation will produce:

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

This "fix-up" ensures that table layout has a predictable structure to operate on.

2.5. 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:

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 with its children and pseudo-elements in the document tree. However, its ::before and ::after pseudo-elements still exist, and are parented by the element’s parent’s principal box along with the rest of the element’s box-generating contents.

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 has no effect on replaced elements and form controls; it computes to inline exactly as if the UA style sheet had specified display: inline !important on such elements.

The element and its descendants generates 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.6. 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:

Behaves as inline flow-root.
Behaves as inline table.
Behaves as inline flex.
Behaves as inline grid.

2.7. Automatic Box Type Transformations

Some layout effects require blockification or inlinification of the box type, which sets the box’s outer display type, if it is not none or contents, to block or inline (respectively).

Some examples of this include:

If a box with a flow inner display type is blockified, its inner display type becomes flow-root. If a box with a flow inner display type 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.

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.

For example, dictionary definitions are often formatted so that the word is inline with the definition:
<dl class='dict'>
  <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.
  <dd>an alphabetical list of terms or words found in or relating
      to a specific subject, text, or dialect, with explanations; a
      brief dictionary.
.dict > dt {
  display: run-in;
.dict > dt::after {
  content: ": "

Which is formatted as:

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:

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

4. Appendix A: Glossary

The following terms are defined here for convenience:

Content that participates in inline layout. Specifically, inline-level boxes and text.
Content that participates in block layout. Specifically, block-level boxes.
A non-replaced inline-level box whose inner display type is flow. The contents of an inline box participate in the same inline formatting context as the inline box itself.
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). Any inline-level box whose inner display type is not flow establishes a new formatting context of the specified inner display type.
block container
A box whose contents participate in a block formatting context. A block container does not necessarily establish a new block formatting context if its parent formatting context is also a block formatting context.
block box
A block-level box that is also a block container.
Used as a shorthand for block box, block-level box, or block container box, where unambiguous.
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.
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.
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 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.


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. Honorable mentions also go to David Baron, Mats Palmgren, and Boris Zbarsky for their feedback.


Changes since the 15 October 2015 Working Draft include:

Changes since the 21 July 2015 Working Draft include:

Changes since the 11 September 2014 Working Draft include:


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

Requirements for Responsible Implementation of CSS

The following sections define several conformance requirements for implementing CSS responsibly, in a way that promotes interoperability in the present and future.

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

Implementations of CR-level Features

Once a specification reaches the Candidate Recommendation stage, implementers should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec, and should avoid exposing a prefixed variant of that feature.

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.


Terms defined by this specification

Terms defined by reference


Normative References

Tab Atkins Jr.. CSS Lists and Counters Module Level 3. 20 March 2014. WD. URL: https://www.w3.org/TR/css-lists-3/
Rossen Atanassov; Arron Eicholz. CSS Positioned Layout Module Level 3. 17 May 2016. WD. URL: https://www.w3.org/TR/css-position-3/
Daniel Glazman; Elika Etemad; Alan Stearns. CSS Pseudo-Elements Module Level 4. 7 June 2016. WD. URL: https://www.w3.org/TR/css-pseudo-4/
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 3. 29 September 2016. CR. URL: https://www.w3.org/TR/css-values-3/
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/CSS2
Bert Bos. Cascading Style Sheets Level 2 Revision 2 (CSS 2.2) Specification. 12 April 2016. WD. URL: https://www.w3.org/TR/CSS22/
Rossen Atanassov; Elika Etemad. CSS Fragmentation Module Level 3. 14 January 2016. CR. URL: https://www.w3.org/TR/css-break-3/
Elika Etemad; Tab Atkins Jr.. CSS Cascading and Inheritance Level 3. 19 May 2016. CR. URL: https://www.w3.org/TR/css-cascade-3/
Tab Atkins Jr.; Elika Etemad; Rossen Atanassov. CSS Flexible Box Layout Module Level 1. 26 May 2016. CR. URL: https://www.w3.org/TR/css-flexbox-1/
Tab Atkins Jr.; Elika Etemad; Rossen Atanassov. CSS Grid Layout Module Level 1. 29 September 2016. CR. URL: https://www.w3.org/TR/css-grid-1/
Daniel Weck. CSS Speech Module. 20 March 2012. CR. URL: https://www.w3.org/TR/css3-speech/
Melinda Grant; et al. CSS Paged Media Module Level 3. 14 March 2013. WD. URL: https://www.w3.org/TR/css3-page/
Elika Etemad; Koji Ishii. CSS Ruby Layout Module Level 1. 5 August 2014. WD. URL: https://www.w3.org/TR/css-ruby-1/
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
Selectors Level 4 URL: https://www.w3.org/TR/selectors4/

Informative References

Rossen Atanassov; Vincent Hardy; Alan Stearns. CSS Exclusions Module Level 1. 15 January 2015. WD. URL: https://www.w3.org/TR/css3-exclusions/
Simon Pieters; Glenn Adams. CSS Object Model (CSSOM). 17 March 2016. WD. URL: https://www.w3.org/TR/cssom-1/

Property Index

Name Value Initial Applies to Inh. %ages Media Ani­mat­able Canonical order Com­puted value
display [ <display-outside> || <display-inside> ] | <display-listitem> | <display-internal> | <display-box> | <display-legacy> inline all elements no n/a all no per grammar as specified