CSS Display Module Level 3

W3C Working Draft,

This version:
http://www.w3.org/TR/2014/WD-css-display-3-20140911/
Latest version:
http://www.w3.org/TR/css-display-3/
Editor's Draft:
http://dev.w3.org/csswg/css-display/
Previous Versions:
http://www.w3.org/TR/2014/WD-css-display-3-20140220/
Feedback:
www-style@w3.org with subject line “[css-display] … message topic …” (archives)
Issue Tracking:
Inline In Spec
Editors:
Tab Atkins Jr. (Google)
fantasai (Invited Expert)

Abstract

This module describes how the CSS formatting box tree is generated from the document element tree and defines the display and box-suppress properties that control 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 http://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.

The (archived) public mailing list www-style@w3.org (see instructions) is preferred for discussion of this specification. When sending e-mail, please put the text “css-display” in the subject, preferably like this: “[css-display] …summary of comment…

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 August 2014 W3C Process Document.

Table of Contents

1. Introduction

This section is not normative.

The display property, introduced in CSS 2.1, defines what kind of boxes an element generates (and whether it generates boxes at all), and how it lays out its contents.

These concepts are actually rather independent, though they’re conflated by the display property. This causes some pain when a property value intended to affect one aspect (such as setting an element to display:none to suppress box generation) affects another aspect (such as losing the memory of what it was before display:none, so that it can be set back to that value later).

This specification subsumes the CSS 2.1 definition of the display property, and redefines it to be a shorthand property for a small family of longhands, each controlling an independent aspect of an element’s "display".

1.1. Module interactions

This specification transforms the display property into a shorthand property, and defines several longhand properties that it expands into or effects.

This module replaces and extends the definition of the display property defined in [CSS21] 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 [CSS21]. Value types not defined in this specification are defined in CSS Level 2 Revision 1 [CSS21]. 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 it has not been repeated explicitly.

2. Controlling Layout Modes: the display property

The display property controls the layout mode of elements (how the element determines the sizes and positions of itself and its descendants), and what boxes they and their descendants generate.

Name: display
Value: [ <display-inside> || <display-outside> ] | <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
Animatable: no
<display-inside>   = flow | flow-root | table | flex | grid | ruby ;
<display-outside>  = block | inline | run-in ;
<display-listitem> = list-item && <display-outside>? && [ flow | flow-root ]?
<display-box> = contents | none ;
<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-legacy>   = inline-block | inline-list-item |
                     inline-table | inline-flex | inline-grid ;

The display property defines two basic qualities of how an element generates boxes:

Additionally, it controls some other box-generation details, such as whether an element is a list item that generates a ::marker pseudo-element.

2.1. The Major Layout Modes

The most common values of display correspond directly to the major layout algorithms in CSS.

The <display-inside> keywords specify the element’s inner display type, and are defined as follows:

flow
The element lays out its contents using flow layout. (Also known as "block" or "inline" layout.) [CSS21]
flow-root
The element lays out its contents using flow layout, and establishes a block formatting context. [CSS21]
table
The element lays out its contents using table layout. [CSS21]
flex
The element lays out its contents using flex layout. [CSS3-FLEXBOX]
grid
The element lays out its contents using grid layout. [CSS3-GRID-LAYOUT]
ruby
The element lays out its contents using ruby layout. [CSS3RUBY]

The <display-outside> keywords specify the element’s outer display type, and are defined as follows:

block
The element generates a block-level box, and participates in a block formatting context. Other formatting contexts, such as flex formatting contexts, may also work with block-level elements. [CSS21]
inline
The element generates an inline-level box. [CSS21]
run-in
The element generates a run-in box. Run-in elements act like inlines or blocks, depending on the surrounding elements. See §4 Run-In Layout for details.

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

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

The list-item keyword makes the element generate a principal box of the specified type together with a ::marker pseudo-element box (see CSS 2.1§12.5 Lists). If neither flow nor flow-root is specified, the principal box’s inner display type defaults to flow. If <display-outside> is unspecified, the principal box’s outer display type defaults to block.

Update Lists module to be referenceable here instead.

2.2. Layout-Specific Display Types

Some layout modes, 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 a 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. [CSS21]

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-root 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 defines 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>
</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>
  </div>
</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 the Table Layout has a predictable structure to operate on.

2.3. Box Generation

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.

Elements with either of these values do not have inner or outer display types, because they don’t 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 with its children and pseudo-elements in the document tree.

contents currently only has an effect on box generation and layout. Other things that care about the document tree are unaffected, like counter scopes. Is this what we want?

none
The element and its descendants generates no boxes. It is recommended that box-suppress be used instead of display: none, so that the element’s display type is automatically preserved for when it’s no longer suppressed.

2.4. Legacy Display Values

CSS level 2 conflated the concepts of inner and outer display types, so that block-level and inline-level variants of the same layout mode were given separate names. Now that display separates those, these legacy values can be mapped into the separate concepts they represent.

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

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

2.5. 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. Controlling box generation: the box-suppress property

display:none was historically used as a "toggle" to switch between displaying an element or not. Making this reversible requires either setting up the CSS cascade properly, or remembering what the display type was before it was set to none. To make this common use-case easier, the box-suppress property was defined to do the same thing, so that toggling whether or not an element displays can now be done without affecting its layout type when it is displayed.

Name: box-suppress
Value: show | discard | hide
Initial: show
Applies to: all elements
Inherited: no
Percentages: n/a
Media: all
Computed value: see prose
Animatable: no

If the computed value of display is none, the computed value of box-suppress is discard. Otherwise, the computed value is the specified value.

show
The element generates boxes as normal, per its display-* properties.
discard
The element generates no boxes at all.
hide
The element generates boxes as normal, but those boxes do not participate in layout in any way, and must not be displayed.

For the purpose of any layout-related information, such as querying for the computed value of the element’s width property, it must be treated as if it did not generate any boxes.

Properties that rely on boxes but do not rely on layout, such as animations, counter-increment, etc., must work as normal on this element and its descendants.

This needs more clarity about what "layout-related" and "participates in layout" means. Does the box still generate anonymous boxes, etc.?

How does this affect speech? Is that "layout"?

We welcome better naming suggestions on this property.

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

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.

Should out-of-flow elements get reparented, left behind, or break apart the sequence? See thread.

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

5. Appendix A: Elements, Boxes, and Fragments

CSS operates on several different types of objects, depending on the stage of processing and what is being done: the element, the box, and the fragment.

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.

An element is an object in the DOM tree returned by the host element. The purpose of an element is to receive styling, so the multiple declarations from the document’s style sheets are converted into values for each property on each element. (The DOM tree also contains text, which is identical to elements except that it can’t be styled directly, only through inheritance.)

Elements generate boxes. Typically, an element generates a single box. Some properties (such as display:none) cause an element and/or its descendants to not generate any boxes at all. Some properties (such as columns: 2) cause an element to generate multiple boxess. Some combinations of properties (such as an element with display:table-cell and a parent element with anything but display:table-row) trigger the creation of anonymous boxes to keep the box tree reasonable.

A box is an object generated from an element according to the display property and other layout-affecting properties, organized into a box tree. The purpose of a box is to organize the document into a structure that is suitable for layout. Boxes have the same styles as their generating element, unless otherwise indicated. They’re referred by their type, typically determined by the display value—a box generated by an element with display: block is called a “block box” or just a “block”.

An anonymous box is generated in certain circumstances where a type of box (such as a table cell box) requires a particular type of parent box (such as a table row box) but the document structure is not written to produce that—anonymous boxes are then generated between the parent and child to provide the required structures. Anonymous boxes are styled as if they inherited from their nearest non-anonymous parent box, unless otherwise specified.

The process of layout generates fragments from boxes.

A fragment is an object representing the result of layout, organized into a fragment tree. Fragments have a size and position, and the same styles as their generating boxes unless otherwise specified.

6. Appendix B: Glossary

The following terms are defined here for convenience:

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
A non-replaced inline-level box whose display 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 or that establishes a new formatting context. (An inline-level box whose display is not flow establishes a new formatting context of the specified type.)
block container
A box whose contents participate in a block formatting context, i.e. one whose computed display value is block.
block box
A block-level box that is a block container.
block
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 [CSS21] Section 9.1.2 and Section 10.1 for details.
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
The thing that makes CSS do the layouts.

wordsmith this.

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

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

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.

We would also like to thank the many JavaScript libraries such as jQuery which have hacked around the "what display should I give it when you call .show()?" problem, making it extremely clear that something needed to be done on our part.

Changes

Changes since the 20 Feburary 2014 Working Draft include:

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.

Experimental implementations

To avoid clashes with future CSS features, the CSS2.1 specification reserves a prefixed syntax for proprietary and experimental extensions to CSS.

Prior to a specification reaching the Candidate Recommendation stage in the W3C process, all implementations of a CSS feature are considered experimental. The CSS Working Group recommends that implementations use a vendor-prefixed syntax for such features, including those in W3C Working Drafts. This avoids incompatibilities with future changes in the draft.

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 http://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

[CSS21]
Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 7 June 2011. REC. URL: http://www.w3.org/TR/CSS2
[CSS3PAGE]
Melinda Grant; et al. CSS Paged Media Module Level 3. 14 March 2013. WD. URL: http://www.w3.org/TR/css3-page/
[CSS3RUBY]
Elika Etemad; Koji Ishii. CSS Ruby Layout Module Level 1. 5 August 2014. WD. URL: http://www.w3.org/TR/css-ruby-1/
[CSS-CASCADE-4]
Elika Etemad; Tab Atkins Jr.. CSS Cascading and Inheritance Level 4. 21 April 2015. WD. URL: http://www.w3.org/TR/css-cascade-4/
[CSS-LISTS-3]
Tab Atkins Jr.. CSS Lists and Counters Module Level 3. 20 March 2014. WD. URL: http://www.w3.org/TR/css-lists-3/
[CSS-MULTICOL-1]
CSS Multi-column Layout Module Level 1 URL: http://www.w3.org/TR/css3-multicol/
[CSS-PSEUDO-4]
Daniel Glazman; Elika Etemad; Alan Stearns. CSS Pseudo-Elements Module Level 4. 15 January 2015. WD. URL: http://www.w3.org/TR/css-pseudo-4/
[CSS-RUBY-1]
Elika Etemad; Koji Ishii. CSS Ruby Layout Module Level 1. 5 August 2014. WD. URL: http://www.w3.org/TR/css-ruby-1/
[CSS-VALUES-3]
CSS Values and Units Module Level 3 URL: http://www.w3.org/TR/css3-values/
[CSS3-FLEXBOX]
Tab Atkins Jr.; Elika Etemad; Rossen Atanassov. CSS Flexible Box Layout Module Level 1. 14 May 2015. LCWD. URL: http://www.w3.org/TR/css-flexbox-1/
[CSS3-GRID-LAYOUT]
Tab Atkins Jr.; Elika Etemad; Rossen Atanassov. CSS Grid Layout Module Level 1. 17 March 2015. WD. URL: http://www.w3.org/TR/css-grid-1/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119

Property Index

Name Value Initial Applies to Inh. %ages Media Animatable Computed value
display [ <display-inside> || <display-outside> ] | <display-listitem> | <display-internal> | <display-box> | <display-legacy> inline all elements no n/a all no as specified
box-suppress show | discard | hide show all elements no n/a all no see prose

Issues Index

Update Lists module to be referenceable here instead.
contents currently only has an effect on box generation and layout. Other things that care about the document tree are unaffected, like counter scopes. Is this what we want?
This needs more clarity about what "layout-related" and "participates in layout" means. Does the box still generate anonymous boxes, etc.?
How does this affect speech? Is that "layout"?
We welcome better naming suggestions on this property.
Should out-of-flow elements get reparented, left behind, or break apart the sequence? See thread.
wordsmith this.