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

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

spec:css2;

type:property; text:overflow;

spec: html;

type: dfn; text: rendered legend

type: element; text: a

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

text: ::first-letter

text: ::first-line

text: ::before

text: ::after

spec: svg2;

type:dfn;

text: container element

text: text content child element

text: renderable element

text: non-rendered element

text: rendered element

text: presentation attribute

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

}

<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 oldids="css-text-run,text-run" 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 <a>anonymous</a> <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]]

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.

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.

<!--

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

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

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

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

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

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

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

-->

<pre class="propdef">

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

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

<td>''block table''

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

<tr>

<td>''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]]

<!--

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

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

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

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

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

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

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

-->

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

<!--

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

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

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

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

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

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

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

-->

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

<!--

██ ████

██ ██

██ ██

██ ██

██ ██

██ ██

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

-->

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

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

with the content specified by its <l spec=css2>'list-style'</l> 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.

<!--

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

██ ██ ██ ██

██ ██ ██

██████ ██ ██

██ ██ ██

██ ██ ██ ██

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

-->

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

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

''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 ''table-cell'' box

must have a ''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>

<!--

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

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

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

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

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

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

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

-->

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

on such elements for forward-compatibility.

<dt><dfn>none</dfn>

<dd>

The [=CSS/element=] and its descendants generate no <a>boxes</a> or <a>text sequences</a>.

Similarly, if a <a>text node</a> is defined to behave as ''display: none'',

it generates no <a>text sequences</a>.

</dl>

Elements with either of these values do not have <a>inner</a> or <a>outer display types</a>,

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.

<span class=non-normative>

For example,

although they may affect which table cell <em>appears</em> in a column,

they do not affect which table cell is associated with a particular column <em>element</em>.

Similarly, they cannot affect which HTML <{summary}> element is associated with a particular table

or whether a <{legend}> is considered to be labelling the contents of a particular <{fieldset}>.

</span>

<!--

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

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

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

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

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

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

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

-->

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:

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

<dt><dfn>inline-block</dfn>

<dd>

Computes to ''inline flow-root''.

<dt><dfn>inline-table</dfn>

<dd>

Computes to ''inline table''.

<dt><dfn>inline-flex</dfn>

<dd>

Computes to ''inline flex''.

<dt><dfn>inline-grid</dfn>

<dd>

Computes to ''inline grid''.

</dl>

Note: Although these keywords and their equivalents compute to the same value,

their [=specified values=] remain distinct.

Note: The {{Window/getComputedStyle()}} serialization rules

will always output these precomposed keywords

rather than the equivalent two-keyword pairs

due to the [[cssom#serializing-css-values|shortest, most backwards-compatible serialization principle]].

<!--

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

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

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

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

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

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

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

-->

Some layout effects require <dfn export lt="blockify|blockification">blockification</dfn>

or <dfn export lt="inlinify|inlinification">inlinification</dfn> of the box type,

which sets the box’s [=computed value|computed=] <a>outer display type</a>

to ''block'' or ''inline'' (respectively).

(This has no effect on <a>display types</a> that generate no box at all,

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

Additionally:

* If a [=block box=] (''block flow'') is <a>inlinified</a>,

its <a>inner display type</a> is set to ''flow-root''

so that it remains a block container.

* If an [=inline box=] (''inline flow'') is <a>inlinified</a>,

it recursively <a>inlinifies</a> all of its in-flow children,

so that no block-level descendants

break up the inline formatting context in which it participates.

* For legacy reasons,

if an [=inline block box=] (''inline flow-root'')

is <a>blockified</a>,

it becomes a ''block'' box

(losing its ''flow-root'' nature).

For consistency,

a ''run-in flow-root'' box

also [=blockifies=]

to a ''block'' box.

* If a [=layout-internal=] box is <a>blockified</a>,

its [=inner display type=] converts to ''flow''

so that it becomes a <a>block container</a>.

<a>Inlinification</a> has no effect on <a>layout-internal</a> boxes.

(However, placement in such an inline context

will typically cause them to be wrapped

in an appropriately-typed anonymous inline-level box.)

Note: There are two methods used to fix up box types when a box is mismatched to its context.

One is transformation of the <a>computed value</a> of 'display', such as <a>blockification</a> and <a>inlinification</a> described here.

The other, taking place during [[#intro|box tree construction]] (after computed values have been determined),

is the creation of intermediary anonymous boxes,

such as happens in <a href="https://www.w3.org/TR/CSS2/tables.html#anonymous-boxes">tables</a>,

[[css-ruby-1#box-fixup|ruby]],

and <a href="https://www.w3.org/TR/CSS21/visuren.html#box-gen">flow</a> layout.

<div class='example'>

Some examples of computed-value fixup include:

<ul>

<li>Absolute positioning or floating an element <a>blockifies</a> the box’s display type. [[CSS2]]

<li>Containment in a <a spec=css-ruby>ruby container</a> <a>inlinifies</a> the box’s display type, as described in [[CSS-RUBY-1]].

<li>A parent with a ''grid'' or ''flex'' 'display' value <a>blockifies</a> the box’s display type. [[CSS-GRID-1]] [[CSS-FLEXBOX-1]]

</ul>

</div>

The [=root element=]’s display type is always <a>blockified</a>,

and its [=principal box=] always establishes an [=independent formatting context=].

This box’s [=containing block=] is the [=initial containing block=].

Additionally, a 'display' of ''display/contents'' computes to ''block'' on the root element.

<!--

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

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

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

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

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

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

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

-->

<!--

<pre class="propdef">

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

The ''display: none'' value was historically used as a "toggle"

to switch between showing and hiding an element.

Making this reversible requires either setting up the CSS <a>cascade</a> carefully,

or remembering what the 'display' value was before it was set to ''display/none''.

To make this common use-case easier,

this module introduces the separate 'display-or-not' property to do the same thing,

so that toggling whether or not an element appears in the formatting tree

can now be done without affecting its display type when it <em>is</em> displayed.

Issue: This property (which needs a better name)

along with a <css>display-type</css> (or possibly <css>display-as</css>) longhand

which takes all values of 'display' other than ''display/none'',

are intended to be longhands of 'display'.

This has not yet been edited in, as this split feature is likely to be deferred to the next level

in order to have time to thoroughly work through and accommodate the

<a href="https://lists.w3.org/Archives/Public/www-style/2016Aug/0025.html">various use cases</a> for showing/hiding an element.

Values have the following meanings:

<dl dfn-type="value" dfn-for="display-or-not">

<dt><dfn>show</dfn>

<dd>

The element generates boxes as normal,

per its 'display-*' properties.

<dt><dfn>discard</dfn>

<dd>

The element generates no boxes at all.

<dt><dfn>hide</dfn>

<dd>

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.

Issue: This needs more clarity about what "layout-related" and "participates in layout" means.

Does the box still generate anonymous boxes, etc.? How does it affect speech?

See <a href="https://lists.w3.org/Archives/Public/www-style/2015Jun/0346.html">proposal</a>.

</dl>

Issue: We welcome better naming suggestions on this property.

Issue: Please send use cases (examples of where this property or something close to it is useful and necessary)

<a href="mailto:[email protected]?subject=%5Bcss-display%5D%20box-suppres%20use%20cases">to the CSSWG</a> so that we can be sure we're designing the details of its behavior correctly.

-->

<!--

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

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

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

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

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

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

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

-->

<pre class='propdef'>

<wpt pathprefix="css/css-flexbox/">

flexible-order.html

</wpt>

Boxes are generally displayed and laid out

in the same order as they appear in the source document.

In some [=formatting contexts=],

the 'order' property can be used to rearrange the order of boxes

to deliberately create a divergence

of the logical order of elements

and their spatial arrangement on the 2D visual canvas.

(See [[#order-accessibility]].)

Specifically,

the 'order' property controls the order in which

[=flex items=] or [=grid items=] appear within their container,

by assigning them to ordinal groups.

It takes a single <dfn value for=order><<integer>></dfn> value,

which specifies which ordinal group the item belongs to.