<pre class='metadata'>

Title: CSS Display Module Level 4

Shortname: css-display

Level: 4

Status: ED

Prepare for TR: no

Group: csswg

Work Status: Testing

Status Text: A <a href="http://test.csswg.org/harness/results/css-display-3_dev/grouped/">preliminary implementation report</a> is available. Further tests will be added during the CR period.

ED: https://drafts.csswg.org/css-display-4/

TR: https://www.w3.org/TR/css-display-4/

Implementation Report: https://wpt.fyi/results/css/css-display?label=master&label=experimental&aligned

Editor: Tab Atkins Jr., Google, http://xanthir.com/contact/, w3cid 42199

Editor: Elika J. Etemad / fantasai, Apple, http://fantasai.inkedblade.net/contact, w3cid 35400

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

Ignored Terms: display-model, display-role, table row group box, absolutely positioned, table formatting context

At Risk: Application of ''::first-letter'' in the presence of run-ins

At Risk: ''display: run-in''

At Risk: All multi-keyword values of 'display'

WPT Path Prefix: css/css-display/

WPT Display: closed

</pre>

<pre class="link-defaults">

spec:css-align-3; type:value; text:stretch

spec:css-backgrounds-3; type:property; text:border

spec:css-break-3; type:dfn; text:fragment;

spec:css-cascade-5; type:dfn;

text:computed value

text:specified value

spec:css-overflow-3;

type:property; text:overflow

type:dfn; text:overflow

spec:css-position-3; type:property; text:position

spec:css-speech-1; type:property; text:speak

spec:dom; type:dfn; text:document tree

spec: html;

type: dfn;

text: rendered legend

text: inert

type: element;

text: a

text: audio

spec:css-pseudo-4; type:selector;

text: ::first-letter

text: ::first-line

text: ::before

text: ::after

spec: svg2;

type: element; text: text

type:dfn;

text: container element

text: text content child element

text: renderable element

text: non-rendered element

text: rendered element

text: presentation attribute

</pre>

<style>

.code-and-figure {

display: table;

margin: 0 auto;

border-spacing: 1em;

}

.code-and-figure > div {

display: table-cell;

vertical-align: middle;

}

.code-and-figure img {

background: transparent;

}

</style>

<h2 id="intro">

Introduction</h2>

<p><em>This section is normative.</em>

CSS takes a source document organized as

a <dfn id="element-tree" oldids="css-element-tree" export for=CSS lt="element tree">tree</dfn>

of <dfn id="elements" oldids="css-element" for=CSS lt="element">elements</dfn>

(which can contain a mix of other [=CSS/elements=] and [=text nodes=])

and <dfn id="text-nodes" oldids="css-text-node" export for=CSS lt="text node">text nodes</dfn>

(which can contain text),

and renders it onto a <a href="https://www.w3.org/TR/CSS2/intro.html#canvas">canvas</a>

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 <dfn id="box-tree" oldids="css-box-tree" export for=CSS>box tree</dfn>,

which represents the formatting structure of the rendered document.

Each <dfn id="box" oldids="css-box" export for=CSS>box</dfn> in the <a>box tree</a>

represents its corresponding [=CSS/element=] (or <a>pseudo-element</a>)

in space and/or time on the canvas,

while each <dfn export for=CSS>text sequence</dfn> in the <a>box tree</a>

likewise represents the corresponding contents of its <a>text nodes</a>.

To create the <a>box tree</a>,

CSS first uses <a href="https://www.w3.org/TR/css-cascade/">cascading and inheritance</a>,

to assign a <a>computed value</a> for each CSS property

to each [=CSS/element=] and <a>text node</a> in the source tree.

(See [[!CSS-CASCADE-3]].)

Then, for each [=CSS/element=],

CSS generates zero or more <a>boxes</a>

as specified by that element's 'display' property.

Typically, an element generates a single <a>box</a>,

the <a>principal box</a>,

which represents itself and contains its contents in the <a>box tree</a>.

However, some 'display' values

(e.g. ''display: list-item'')

generate more than one box

(e.g. a <a href="https://www.w3.org/TR/CSS2/visuren.html#principal-box">principal block box</a> and a child <a href="https://www.w3.org/TR/CSS2/generate.html#lists">marker box</a>).

And some values

(such as ''display/none'' or ''display/contents'')

cause the [=CSS/element=] and/or its descendants to not generate any <a>boxes</a> at all.

<a>Boxes</a> are often referred to by their 'display' type--

e.g. a <a>box</a> generated by an element with ''display: block'' is called a “block box” or just a “block”.

A <a>box</a> is assigned the same styles as its generating [=CSS/element=], unless otherwise indicated.

In general, <a>inherited properties</a> are assigned to the <a>principal box</a>,

and then inherit through the box tree

to any other boxes generated by the same element.

Non-inherited properties default to applying to the <a>principal box</a>,

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 <a>table grid box</a>,

not to its <a lt="principal box">principal</a> <a>table wrapper box</a>.

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 <a>text nodes</a> generates a <a>text sequence</a>

containing their text contents,

which is assigned the same styles as the generating <a>text nodes</a>.

If the sequence contains no text, however, it does not generate a <a>text sequence</a>.

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 <dfn export for=CSS>parent box</dfn>

of an element’s <a>principal box</a>

is the <a>principal box</a>

of its nearest ancestor element that generates a <a>box</a>;

however, there are some exceptions,

such as for ''run-in'' boxes,

display types (like tables) that generate multiple container boxes,

and intervening <a>anonymous boxes</a>.

An <dfn id="anonymous" oldids="css-anonymous" for=CSS lt="anonymous|anonymous box" export>anonymous box</dfn> is a box that is not associated with any element.

<a>Anonymous boxes</a> are generated in certain circumstances

to fix up the <a>box tree</a> when it requires a particular nested structure

that is not provided by the boxes generated from the <a>element tree</a>.

For example, a <a href="https://www.w3.org/TR/CSS2/tables.html#table-display">table cell box</a>

requires a particular type of parent box (the <a href="https://www.w3.org/TR/CSS2/tables.html#table-display">table row box</a>),

and will generate an [=CSS/anonymous=] <a href="https://www.w3.org/TR/CSS2/tables.html#table-display">table row box</a> around itself

if its parent is not a <a href="https://www.w3.org/TR/CSS2/tables.html#table-display">table row box</a>.

(See [[CSS2]] &sect; <a href="https://www.w3.org/TR/CSS2/tables.html#anonymous-boxes">17.2.1</a>.)

Unlike element-generated boxes, whose styles inherit strictly through the element tree,

anonymous boxes (which only exist in the <a>box tree</a>)

<a href="https://www.w3.org/TR/css-cascade/#inheriting">inherit</a> through their <a>box tree</a> parentage.

In the course of layout,

<a>boxes</a> and <a>text sequences</a> can be broken into multiple <a>fragments</a>.

This happens, for example, when an <a>inline box</a> and/or <a>text sequence</a>

is broken across lines,

or when a <a>block box</a> is broken across pages or columns,

in a process called <a>fragmentation</a>.

It can also happen due to bidi reordering of text

(see [[css-writing-modes-3#bidi-algo|Applying the Bidirectional Reordering Algorithm]]

in [[css-writing-modes-3#text-direction|CSS Writing Modes]])

or higher-level <a>display type</a> box splitting,

e.g. <a href="https://www.w3.org/TR/CSS2/visuren.html#img-anon-block">block-in-inline splitting</a>

(see <a href="https://www.w3.org/TR/CSS2/visuren.html#box-gen">CSS2&sect;9.2</a>)

or <a href="https://www.w3.org/TR/css-multicol-1/#spanning-columns">column-spanner-in-block</a> splitting

(see <a href="https://www.w3.org/TR/css-multicol-1/#spanning-columns">CSS Multi-column Layout</a>).

A <a>box</a> therefore consists of one or more <a>box fragments</a>,

and a <a>text sequence</a> consists of one or more <a lt=fragment>text fragments</a>.

See [[CSS-BREAK-3]] for more information on <a>fragmentation</a>.

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 <a href="#sotd">report errors</a> 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 <a href="https://www.w3.org/TR/css-speech-1/#aural-model">CSS Speech Module</a>.

[[!CSS-SPEECH-1]]

<wpt>

empty-text-baseline-001.html

empty-text-baseline-002.html

</wpt>

<h3 id="placement">

Module interactions</h3>

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 <code>::first-line</code> or <code>::first-letter</code> pseudo-elements.

<wpt>

display-first-letter-001.html

display-first-line-001.html

display-first-line-002.html

display-inline-dynamic-001.html

</wpt>

<h3 id="values">

Value Definitions</h3>

This specification follows the <a href="https://www.w3.org/TR/CSS2/about.html#property-defs">CSS property definition conventions</a> from [[!CSS2]]

using the <a href="https://www.w3.org/TR/css-values-3/#value-defs">value definition syntax</a> from [[!CSS-VALUES-3]].

Value types not defined in this specification are defined in CSS Values &amp; 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 <a>CSS-wide keywords</a> as their property value.

For readability they have not been repeated explicitly.

<!--

████████ ████ ██████ ████████ ██ ███ ██ ██

██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ ██ ██ ██ ████

██ ██ ██ ██████ ████████ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ █████████ ██

██ ██ ██ ██ ██ ██ ██ ██ ██ ██

████████ ████ ██████ ██ ████████ ██ ██ ██

-->

<h2 id="the-display-properties">

Box Layout Modes: the 'display' property</h2>

<pre class="propdef">

Name: display

Value: [ <<display-outside>> || <<display-inside>> ] | <<display-listitem>> | <<display-internal>> | <<display-box>> | <<display-legacy>>

Initial: inline

Applies to: all elements

Inherited: no

Computed value: a pair of keywords representing the [=inner display type|inner=] and [=outer display type|outer=] display types plus optional ''list-item'' flag, or a <<display-internal>> or <<display-box>> keyword; see prose in a variety of specs for computation rules

Animation type: see [[#display-animation]]

</pre>

<p class=all-media>User agents are expected to support this property on all media, including non-visual ones.

The 'display' property defines an element's <dfn export>display type</dfn>,

which consists of the two basic qualities of how an element generates boxes:

* the <dfn export local-lt="inner">inner display type</dfn>,

which defines (if it is a <a lt="replaced element">non-replaced element</a>) the kind of <a>formatting context</a> it generates,

dictating how its descendant boxes are laid out.

(The inner display of a <a>replaced element</a> is outside the scope of CSS.)

* the <dfn export local-lt="outer">outer display type</dfn>,

which dictates how the [=principal box=] itself participates in <a>flow layout</a>.

[=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 ''display/none'', which causes the element's entire subtree to be left out of the box tree.

<div class="advisement">

The 'display' property has no effect on an element’s semantics:

these are defined by the <a spec=selectors-4>document language</a> and <em>are not affected by CSS</em>.

Aside from the ''display/none'' value,

which also affects the aural/speech output [[!CSS-SPEECH-1]]

and interactivity of an element and its descendants,

the 'display' property only affects visual layout:

its purpose is to allow designers freedom

to change the layout behavior of an element

<em>without</em> affecting the underlying document semantics.

</div>

Values are defined as follows:

<pre class='prod'>

<dfn>&lt;display-outside></dfn> = block | inline | run-in

<dfn>&lt;display-inside></dfn> = flow | flow-root | table | flex | grid | ruby

<dfn>&lt;display-listitem></dfn> = <<display-outside>>? && [ flow | flow-root ]? && list-item

<dfn>&lt;display-internal></dfn> = 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

<dfn>&lt;display-box></dfn> = contents | none

<dfn>&lt;display-legacy></dfn> = inline-block | inline-table | inline-flex | inline-grid

</pre>

The following informative table summarizes the values of 'display':

<style>

#display-value-summary td,

#display-value-summary th { text-align: left; }

</style>

<table class='data' id="display-value-summary">

<thead>

<tr>

<th>Short 'display'

<th>Full 'display'

<th>Generated box

<tbody title="Box Suppression Display Types">

<tr>

<td>''display/none''

<td>&mdash;

<td>subtree omitted from <a>box tree</a>

<tr>

<td>''display/contents''

<td>&mdash;

<td>element replaced by contents in <a>box tree</a>

<tbody title="Flow Layout Display Types">

<tr>

<td>''block''

<td>''block flow''

<td><a>block-level</a> <a>block container</a>

<abbr title="also known as">aka</abbr> <a>block box</a>

<tr>

<td>''flow-root''

<td>''block flow-root''

<td><a>block-level</a> <a>block container</a>

that establishes a new <a>block formatting context</a> (<a>BFC</a>)

<tr>

<td>''inline''

<td>''inline flow''

<td><a>inline box</a>

<tr>

<td>''inline-block''

<td>''inline flow-root''

<td><a>inline-level</a> <a>block container</a>

<abbr title="also known as">aka</abbr> <dfn export lt="inline block | inline block box">inline block</dfn>

<tr>

<td>''run-in''

<td>''run-in flow''

<td><a>run-in box</a> (<a>inline box</a> with special box-tree-munging rules)

<tr>

<td>''list-item''

<td>''block flow list-item''

<td><a>block box</a>

with additional <a href="https://www.w3.org/TR/CSS2/generate.html#lists">marker box</a>

<tr>

<td>''inline list-item''

<td>''inline flow list-item''

<td><a>inline box</a>

with additional <a href="https://www.w3.org/TR/CSS2/generate.html#lists">marker box</a>

<tbody title="Formatting Context Root Display Types">

<tr>

<td>''flex''

<td>''block flex''

<td><a>block-level</a> <a>flex container</a>

<tr>

<td>''inline-flex''

<td>''inline flex''

<td><a>inline-level</a> <a>flex container</a>

<tr>

<td>''grid''

<td>''block grid''

<td><a>block-level</a> <a>grid container</a>

<tr>

<td>''inline-grid''

<td>''inline grid''

<td><a>inline-level</a> <a>grid container</a>

<tr>

<td>''ruby''

<td>''inline ruby''

<td><a>inline-level</a> <a>ruby container</a>

<tr>

<td>''block ruby''

<td>''block ruby''

<td><a>block box</a> containing <a>ruby container</a>

<tr>

<td>''display/table''

<td>''block table''

<td><a>block-level</a> <a>table wrapper box</a> containing <a>table grid box</a>

<tr>

<td>''display/inline-table''

<td>''inline table''

<td><a>inline-level</a> <a>table wrapper box</a> containing <a>table grid box</a>

<tbody title="Layout-internal display types">

<!--

<tr>

<td>''table-cell''

<td>''table-cell flow-root''

<td>table cell <a>block container</a>

<tr>

<td>''table-caption''

<td>''table-caption flow-root''

<td>table cell <a>block container</a>

<tr>

<td>''ruby-base''

<td>''ruby-base flow''

<td><a href="#layout-specific-display">layout-specific internal box</a>

<tr>

<td>''ruby-text''

<td>''ruby-text flow''

<td><a href="#layout-specific-display">layout-specific internal box</a>

-->

<tr>

<td><<display-internal>> types

<td>&mdash;

<td><a href="#layout-specific-display">layout-specific internal box</a>

</table>

Note: Following the precedence rules of “most backwards-compatible, then shortest”,

serialization of equivalent 'display' values uses the “Short 'display'” column.

[[CSSOM]]

<wpt>

animations/display-interpolation.html

display-math-on-non-mathml-elements.html

display-math-on-pseudo-elements-001.html

display-math-on-pseudo-elements-002.html

display-none-root-hit-test-crash.html

inheritance.html

parsing/display-computed.html

parsing/display-invalid.html

parsing/display-valid.html

select-4-option-optgroup-display-none.html

textarea-display.html

</wpt>

<!--

███████ ██ ██ ████████ ████████ ████████

██ ██ ██ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██████ ████████

██ ██ ██ ██ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ ██ ██

███████ ███████ ██ ████████ ██ ██

-->

<h3 id="outer-role">

Outer Display Roles for Flow Layout: the ''block'', ''inline'', and ''run-in'' keywords</h3>

The <<display-outside>> keywords specify the element's <a>outer display type</a>,

which is essentially its [=principal box’s=] role in <a>flow layout</a>.

They are defined as follows:

<dl dfn-type="value" dfn-for="display, <display-outside>">

<dt><dfn>block</dfn>

<dd>

The element generates a box that is

<dfn export dfn for lt="block-level box">block-level</dfn>

when placed in <a>flow layout</a>. [[!CSS2]]

<dt><dfn>inline</dfn>

<dd>

The element generates a box that is

<dfn export dfn for lt="inline-level box">inline-level</dfn>

when placed in <a>flow layout</a>. [[!CSS2]]

<dt><dfn>run-in</dfn>

<dd>

The element generates an <a>run-in box</a>,

which is a type of <a>inline-level box</a>

with special behavior that attempts to merge it into a subsequent block container.

See [[#run-in-layout]] for details.

</dl>

Note: [=Outer display types=] do affect [=replaced elements=].

If a <<display-outside>> value is specified but <<display-inside>> is omitted,

the element's <a>inner display type</a> defaults to ''flow''.

<wpt>

display-change-iframe.html

display-change-object-iframe.html

run-in/after-content-display-004.xht

run-in/anonymous-box-generation-002.xht

run-in/background-applies-to-011.xht

run-in/background-attachment-applies-to-011.xht

run-in/background-color-applies-to-011.xht

run-in/background-image-applies-to-011.xht

run-in/background-position-applies-to-011.xht

run-in/background-repeat-applies-to-011.xht

run-in/before-content-display-004.xht

run-in/border-applies-to-011.xht

run-in/border-bottom-applies-to-011.xht

run-in/border-bottom-color-applies-to-011.xht

run-in/border-bottom-style-applies-to-011.xht

run-in/border-bottom-width-applies-to-011.xht

run-in/border-collapse-applies-to-004.xht

run-in/border-color-applies-to-011.xht

run-in/border-left-applies-to-011.xht

run-in/border-left-color-applies-to-011.xht

run-in/border-left-style-applies-to-011.xht

run-in/border-left-width-applies-to-011.xht

run-in/border-right-applies-to-011.xht

run-in/border-right-color-applies-to-011.xht

run-in/border-right-style-applies-to-011.xht

run-in/border-right-width-applies-to-011.xht

run-in/border-spacing-applies-to-004.xht

run-in/border-style-applies-to-011.xht

run-in/border-top-applies-to-011.xht

run-in/border-top-color-applies-to-011.xht

run-in/border-top-style-applies-to-011.xht

run-in/border-top-width-applies-to-011.xht

run-in/border-width-applies-to-011.xht

run-in/bottom-applies-to-011.xht

run-in/caption-side-applies-to-004.xht

run-in/clear-applies-to-011.xht

run-in/clear-runin-001.xht

run-in/color-applies-to-011.xht

run-in/counter-increment-applies-to-011.xht

run-in/counter-reset-applies-to-011.xht

run-in/cursor-applies-to-011.xht

run-in/direction-applies-to-011.xht

run-in/display-004.xht

run-in/empty-cells-applies-to-004.xht

run-in/first-line-pseudo-009.xht

run-in/float-applies-to-011.xht

run-in/font-applies-to-004.xht

run-in/font-family-applies-to-004.xht

run-in/font-size-applies-to-004.xht

run-in/font-style-applies-to-004.xht

run-in/font-variant-applies-to-004.xht

run-in/font-weight-applies-to-004.xht

run-in/height-applies-to-011.xht

run-in/left-applies-to-011.xht

run-in/letter-spacing-applies-to-004.xht

run-in/line-height-applies-to-011.xht

run-in/list-style-applies-to-011.xht

run-in/list-style-image-applies-to-011.xht

run-in/list-style-position-applies-to-011.xht

run-in/list-style-type-applies-to-011.xht

run-in/margin-applies-to-011.xht

run-in/margin-bottom-applies-to-011.xht

run-in/margin-left-applies-to-011.xht

run-in/margin-right-applies-to-011.xht

run-in/margin-top-applies-to-011.xht

run-in/max-height-applies-to-011.xht

run-in/max-width-applies-to-011.xht

run-in/min-height-applies-to-011.xht

run-in/min-width-applies-to-011.xht

run-in/outline-applies-to-011.xht

run-in/outline-color-applies-to-011.xht

run-in/outline-style-applies-to-011.xht

run-in/outline-width-applies-to-011.xht

run-in/overflow-applies-to-011.xht

run-in/padding-applies-to-011.xht

run-in/padding-bottom-applies-to-011.xht

run-in/padding-left-applies-to-011.xht

run-in/padding-right-applies-to-011.xht

run-in/padding-top-applies-to-011.xht

run-in/position-applies-to-011.xht

run-in/quotes-applies-to-011.xht

run-in/right-applies-to-011.xht

run-in/run-in-001.xht

run-in/run-in-002.xht

run-in/run-in-003.xht

run-in/run-in-004.xht

run-in/run-in-005.xht

run-in/run-in-006.xht

run-in/run-in-007.xht

run-in/run-in-008.xht

run-in/run-in-009.xht

run-in/run-in-010.xht

run-in/run-in-011.xht

run-in/run-in-012.xht

run-in/run-in-013.xht

run-in/run-in-abspos-between-001.xht

run-in/run-in-abspos-between-002.xht

run-in/run-in-abspos-between-003.xht

run-in/run-in-basic-001.xht

run-in/run-in-basic-002.xht

run-in/run-in-basic-003.xht

run-in/run-in-basic-004.xht

run-in/run-in-basic-005.xht

run-in/run-in-basic-006.xht

run-in/run-in-basic-007.xht

run-in/run-in-basic-008.xht

run-in/run-in-basic-009.xht

run-in/run-in-basic-010.xht

run-in/run-in-basic-011.xht

run-in/run-in-basic-012.xht

run-in/run-in-basic-013.xht

run-in/run-in-basic-014.xht

run-in/run-in-basic-015.xht

run-in/run-in-basic-016.xht

run-in/run-in-basic-017.xht

run-in/run-in-basic-018.xht

run-in/run-in-block-between-001.xht

run-in/run-in-block-between-002.xht

run-in/run-in-block-between-003.xht

run-in/run-in-breaking-001.xht

run-in/run-in-breaking-002.xht

run-in/run-in-clear-001.xht

run-in/run-in-clear-002.xht

run-in/run-in-contains-abspos-001.xht

run-in/run-in-contains-block-001.xht

run-in/run-in-contains-block-002.xht

run-in/run-in-contains-block-003.xht

run-in/run-in-contains-block-004.xht

run-in/run-in-contains-block-005.xht

run-in/run-in-contains-block-inside-inline-001.xht

run-in/run-in-contains-block-inside-inline-002.xht

run-in/run-in-contains-block-inside-inline-003.xht

run-in/run-in-contains-float-001.xht

run-in/run-in-contains-inline-001.xht

run-in/run-in-contains-inline-002.xht

run-in/run-in-contains-inline-003.xht

run-in/run-in-contains-inline-004.xht

run-in/run-in-contains-inline-005.xht

run-in/run-in-contains-inline-006.xht

run-in/run-in-contains-inline-007.xht

run-in/run-in-contains-inline-block-001.xht

run-in/run-in-contains-inline-table-001.xht

run-in/run-in-contains-relpos-block-001.xht

run-in/run-in-contains-relpos-block-002.xht

run-in/run-in-contains-relpos-block-003.xht

run-in/run-in-contains-run-in-001.xht

run-in/run-in-contains-run-in-002.xht

run-in/run-in-contains-run-in-003.xht

run-in/run-in-contains-table-001.xht

run-in/run-in-contains-table-002.xht

run-in/run-in-contains-table-003.xht

run-in/run-in-contains-table-caption-001.xht

run-in/run-in-contains-table-cell-001.xht

run-in/run-in-contains-table-column-001.xht

run-in/run-in-contains-table-column-group-001.xht

run-in/run-in-contains-table-inside-inline-001.xht

run-in/run-in-contains-table-inside-inline-002.xht

run-in/run-in-contains-table-inside-inline-003.xht

run-in/run-in-contains-table-row-001.xht

run-in/run-in-contains-table-row-group-001.xht

run-in/run-in-display-none-between-001.xht

run-in/run-in-display-none-between-002.xht

run-in/run-in-display-none-between-003.xht

run-in/run-in-fixedpos-between-001.xht

run-in/run-in-fixedpos-between-002.xht

run-in/run-in-fixedpos-between-003.xht

run-in/run-in-float-between-001.xht

run-in/run-in-float-between-002.xht

run-in/run-in-float-between-003.xht

run-in/run-in-inherit-001.xht

run-in/run-in-inheritance-001.xht

run-in/run-in-inline-between-001.xht

run-in/run-in-inline-between-002.xht

run-in/run-in-inline-between-003.xht

run-in/run-in-inline-block-between-001.xht

run-in/run-in-inline-block-between-002.xht

run-in/run-in-inline-block-between-003.xht

run-in/run-in-inline-table-between-001.xht

run-in/run-in-inline-table-between-002.xht

run-in/run-in-inline-table-between-003.xht

run-in/run-in-linebox-001.xht

run-in/run-in-linebox-002.xht

run-in/run-in-listitem-between-001.xht

run-in/run-in-listitem-between-002.xht

run-in/run-in-listitem-between-003.xht

run-in/run-in-relpos-between-001.xht

run-in/run-in-relpos-between-002.xht

run-in/run-in-relpos-between-003.xht

run-in/run-in-replaced-001.xht

run-in/run-in-restyle-001.xht

run-in/run-in-restyle-002.xht

run-in/run-in-restyle-003.xht

run-in/run-in-run-in-between-001.xht

run-in/run-in-run-in-between-002.xht

run-in/run-in-run-in-between-003.xht

run-in/run-in-run-in-between-004.xht

run-in/run-in-run-in-between-005.xht

run-in/run-in-run-in-between-006.xht

run-in/run-in-run-in-between-007.xht

run-in/run-in-run-in-between-008.xht

run-in/run-in-table-between-001.xht

run-in/run-in-table-between-002.xht

run-in/run-in-table-between-003.xht

run-in/run-in-table-cell-between-001.xht

run-in/run-in-table-cell-between-002.xht

run-in/run-in-table-cell-between-003.xht

run-in/run-in-table-row-between-001.xht

run-in/run-in-table-row-between-002.xht

run-in/run-in-table-row-between-003.xht

run-in/run-in-text-between-001.xht

run-in/run-in-text-between-002.xht

run-in/run-in-text-between-003.xht

run-in/run-in-text-between-004.xht

run-in/run-in-text-between-005.xht

run-in/table-anonymous-block-001.xht

run-in/table-layout-applies-to-004.xht

run-in/text-align-applies-to-004.xht

run-in/text-decoration-applies-to-004.xht

run-in/text-indent-applies-to-004.xht

run-in/text-transform-applies-to-004.xht

run-in/top-applies-to-011.xht

run-in/unicode-bidi-applies-to-011.xht

run-in/vertical-align-applies-to-011.xht

run-in/visibility-applies-to-011.xht

run-in/white-space-applies-to-004.xht

run-in/width-applies-to-011.xht

run-in/word-spacing-applies-to-004.xht

run-in/z-index-applies-to-011.xht

</wpt>

<!--

████ ██ ██ ██ ██ ████████ ████████

██ ███ ██ ███ ██ ██ ██ ██

██ ████ ██ ████ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ ██ ██████ ████████

██ ██ ████ ██ ████ ██ ██ ██

██ ██ ███ ██ ███ ██ ██ ██

████ ██ ██ ██ ██ ████████ ██ ██

-->

<h3 id="inner-model">

Inner Display Layout Models: the ''flow'', ''flow-root'', ''display/table'', ''flex'', ''grid'', and ''ruby'' keywords</h3>

The <<display-inside>> keywords specify the element's <a>inner display type</a>,

which defines the type of formatting context that lays out its contents

(assuming it is a <a lt="replaced element">non-replaced element</a>).

They are defined as follows:

<dl dfn-type="value" dfn-for="display, <display-inside>">

<dt><dfn>flow</dfn>

<dd>

The element lays out its contents using <dfn dfn for export>flow layout</dfn>

(<a href="https://www.w3.org/TR/CSS2/visuren.html">block-and-inline layout</a>).

If its <a>outer display type</a> is ''inline'' or ''run-in'',

and it is participating in a

<a lt="block formatting context">block</a>

or <a lt="inline formatting context">inline</a>

formatting context,

then it generates an <a>inline box</a>.

Otherwise it generates a <a>block container</a> 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 <a>formatting context</a>,

it either establishes a new <a>block formatting context</a> for its contents

or integrates its contents into its parent <a>formatting context</a>.

See <a href="https://www.w3.org/TR/CSS2/visuren.html">CSS2.1 Chapter 9</a>. [[!CSS2]]

A <a>block container</a> that establishes a new <a>block formatting context</a>

is considered to have a used <a>inner display type</a> of ''flow-root''.

<dt><dfn>flow-root</dfn>

<dd>

The element generates a <a>block container</a> box,

and lays out its contents using <a>flow layout</a>.

It always establishes a new <a>block formatting context</a> for its contents. [[!CSS2]]

<dt><dfn>table</dfn>

<dd>

The element generates a principal <a>table wrapper box</a>

that establishes a <a>block formatting context</a>,

and which contains

an additionally-generated <a>table grid box</a>

that establishes a <a>table formatting context</a>. [[!CSS2]]

<dt><dfn>flex</dfn>

<dd>

The element generates a principal <a>flex container</a> box

and establishes a <a>flex formatting context</a>. [[!CSS-FLEXBOX-1]]

<dt><dfn>grid</dfn>

<dd>

The element generates a principal <a>grid container</a> box,

and establishes a <a>grid formatting context</a>. [[!CSS-GRID-1]]

(Grids using ''subgrid'' might not generate a new [=grid formatting context=];

see [[CSS-GRID-2]] for details.)

<dt><dfn>ruby</dfn>

<dd>

The element generates a <a>ruby container</a> box

and establishes a <a>ruby formatting context</a>

in addition to integrating its base-level contents

into its parent <a>formatting context</a>

(if it is inline)

or generating a wrapper box of the appropriate <a>outer display type</a>

(if it is not). [[!CSS-RUBY-1]]

</dl>

If a <<display-inside>> value is specified but <<display-outside>> is omitted,

the element's <a>outer display type</a> defaults to ''block''--

except for ''ruby'', which defaults to ''inline''.

<wpt>

display-flow-root-001.html

display-flow-root-002.html

display-none-inline-img.html

</wpt>

<!--

██ ████

██ ██

██ ██

██ ██

██ ██

██ ██

████████ ████

-->

<h3 id="list-items">

Generating Marker Boxes: the ''list-item'' keyword</h3>

The <dfn value for="display, <display-list-item>">list-item</dfn> keyword

causes the element to generate a ''::marker'' pseudo-element [[!CSS-PSEUDO-4]]

with the content specified by its <code>list-style</code> properties

(<a href="https://www.w3.org/TR/CSS2/generate.html#lists">CSS 2.1§12.5 Lists</a>) [[!CSS2]]

together with a principal box of the specified type for its own contents.

If no <a>inner display type</a> value is specified,

the principal box's <a>inner display type</a> defaults to ''flow''.

If no <a>outer display type</a> value is specified,

the principal box's <a>outer display type</a> defaults to ''block''.

Note: In this level, as restricted in the grammar,

list-items are limited to the <a>Flow Layout</a> display types

(''block''/''inline''/''run-in'' with ''flow''/''flow-root'' inner types).

This restriction may be relaxed in a future level of this module.

<wpt>

display-flow-root-list-item-001.html

display-list-item-height-after-dom-change.html

</wpt>

<!--

████████ ████████ ██████

██ ██ ██ ██

██ ██ ██

██████ ██ ██

██ ██ ██

██ ██ ██ ██

████████ ██ ██████

-->

<h3 id="layout-specific-display">

Layout-Internal Display Types: the ''table-*'' and ''ruby-*'' keywords</h3>

Some layout models, such as ''display/table'' and ''ruby'',

have a complex internal structure,

with several different roles that their children and descendants can fill.

This section defines those “<dfn export>layout-internal</dfn>” 'display' values,

which only have meaning within that particular layout mode.

Unless otherwise specified,

both the <a>inner display type</a> and the <a>outer display type</a>

of elements using these 'display' values

are set to the given keyword.

When the 'display' property of a [=replaced element=] computes to

one of the [=layout-internal=] values,

it is handled as having a used value of ''display/inline''.

White space collapsing and anonymous box generation must happen around those replaced elements

based on that ''display/inline'' value,

as if they never had a [=layout-internal=] display value applied to them.

Advisement: Authors should not assign a [=layout-internal=] display value to [=replaced elements=].

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

<dl export dfn-type=value dfn-for="display, <display-internal>">

<dt><dfn>table-row-group</dfn>, <dfn>table-header-group</dfn>, <dfn>table-footer-group</dfn>, <dfn>table-row</dfn>, <dfn>table-cell</dfn>, <dfn>table-column-group</dfn>, <dfn>table-column</dfn>

<dd>

The element is an <dfn dfn for>internal table element</dfn>.

It generates the appropriate <dfn dfn for>internal table box</dfn>

which participates in a <a>table formatting context</a>.

See <a href="https://www.w3.org/TR/CSS2/tables.html#table-display">CSS2&sect;17.2</a> [[!CSS2]].

''display/table-cell'' boxes have a ''flow-root'' <a>inner display type</a>.

<dt><dfn>table-caption</dfn>

<dd>

The element generates a <dfn dfn for>table caption box</dfn>,

which is a <a>block box</a> with special behavior with respect to table and table wrapper boxes.

See <a href="https://www.w3.org/TR/CSS2/tables.html#table-display">CSS2&sect;17.2</a> [[!CSS2]].

''display/table-caption'' boxes have a ''flow-root'' <a>inner display type</a>.

<dt>

<dt><dfn>ruby-base</dfn>, <dfn>ruby-text</dfn>, <dfn>ruby-base-container</dfn>, <dfn>ruby-text-container</dfn>

<dd>

The element is an <dfn dfn for>internal ruby element</dfn>.

It generates the appropriate <dfn dfn for>internal ruby box</dfn>

which participates in a <a>ruby formatting context</a>. [[!CSS-RUBY-1]]

''ruby-base'' and ''ruby-text'' have a ''flow'' <a>inner display type</a>.

</dl>

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 class='example'>

For example, Table Layout requires that a ''display/table-cell'' box

must have a ''display/table-row'' parent box.

If it is misparented, like so:

<pre class="lang-markup">

&lt;div style="display:block;">

&lt;div style="display:table-cell">...&lt;/div>

&lt;/div>

</pre>

It will generate wrapper boxes around itself,

producing a structure like:

<pre>

block box

└anonymous table box

└anonymous table-row-group box

└anonymous table-row box

└table-cell box

</pre>

Even if the parent is another <a>internal table element</a>,

if it's not the <em>correct</em> one,

wrapper boxes will be generated.

For example, in the following markup:

<pre class="lang-markup">

&lt;div style="display:table;">

&lt;div style="display:table-row">

&lt;div style="display:table-cell">...&lt;/div>

&lt;/div>

&lt;/div>

</pre>

Anonymous wrapper box generation will produce:

<pre>

table box

└anonymous table-row-group box

└table-row box

└table-cell box

</pre>

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

</div>

<wpt title="This section lacks tests."></wpt>

<!--

████████ ██ ██ ██ ███████ ██ ██ ████████

██ ██ ████ ███ ██ ██ ██ ███ ██ ██

██ ██ ██ ████ ██ ██ ██ ████ ██ ██

██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██████

██ ██ ██ ██ ████ ██ ██ ██ ████ ██

██ ██ ████ ██ ███ ██ ██ ██ ███ ██

████████ ██ ██ ██ ███████ ██ ██ ████████

-->

<h3 id="box-generation">

Box Generation: the ''display/none'' and ''display/contents'' keywords</h3>

While 'display' can control the <em>types</em> 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:

<dl dfn-type=value dfn-for="display, <display-box>">

<dt><dfn>contents</dfn>

<dd>

The element itself does not generate any boxes,

but its children and pseudo-elements still generate <a>boxes</a> and <a>text sequences</a> 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, event handling,

and property <a>inheritance</a>,

are not affected.

<strong>As of writing, however,

<a href="https://github.com/w3c/csswg-drafts/issues/3040">this is not implemented correctly in major browsers</a>,

so using this feature on the Web must be done with care

as it can prevent accessibility tools

from accessing the element’s semantics.</strong>

This value computes to ''display: none'' on replaced elements

and other elements whose rendering is not entirely controlled by CSS;

see [[#unbox]] 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''