CSS Display Module Level 4
CSS Display Module Level 4
Editor’s Draft
18 January 2025
More details about this document
This version:
Latest published version:
Implementation Report:
Feedback:
CSSWG Issues Repository
Inline In Spec
Editors:
Tab Atkins Jr.
Google
Elika J. Etemad / fantasai
Apple
Suggest an Edit for this Spec:
GitHub Editor
Test Suite:
World Wide Web Consortium
W3C
liability
trademark
and
permissive document license
rules apply.
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.
CSS
is a language for describing the rendering of structured documents
(such as HTML and XML)
on screen, on paper, etc.
Status of this document
This is a public copy of the editors’ draft.
It is provided for discussion only and may change at any moment.
Its publication here does not imply endorsement of its contents by W3C.
Don’t cite this document other than as work in progress.
Please send feedback
by
filing issues in GitHub
(preferred),
including the spec code “css-display” in the title, like this:
“[css-display]
…summary of comment…
”.
All issues and comments are
archived
Alternately, feedback can be sent to the (
archived
) public mailing list
www-style@w3.org
This document is governed by the
18 August 2025 W3C Process Document
preliminary implementation report
is available. Further tests will be added during the CR period.
The following features are at-risk, and may be dropped during the CR period:
Application of
::first-letter
in the presence of run-ins
display: run-in
All multi-keyword values of
display
“At-risk” is a W3C Process term-of-art, and does not necessarily imply that the feature is in danger of being dropped or delayed. It means that the WG believes the feature may have difficulty being interoperably implemented in a timely manner, and marking it as such allows the WG to drop the feature if necessary when transitioning to the Proposed Rec stage, without having to publish a new Candidate Rec without the feature first.
1.
Introduction
This section is normative.
CSS takes a source document organized as
tree
of
elements
(which can contain a mix of other
elements
and
text nodes
and
text nodes
(which can contain text),
and renders it onto a
canvas
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
box tree
which represents the formatting structure of the rendered document.
Each
box
in the
box tree
represents its corresponding
element
(or
pseudo-element
in space and/or time on the canvas,
while each
text sequence
in the
box tree
likewise represents the corresponding contents of its
text nodes
To create the
box tree
CSS first uses
cascading and inheritance
to assign a
computed value
for each CSS property
to each
element
and
text node
in the source tree.
(See
[CSS-CASCADE-3]
.)
Then, for each
element
CSS generates zero or more
boxes
as specified by that element’s
display
property.
Typically, an element generates a single
box
the
principal box
which represents itself and contains its contents in the
box tree
However, some
display
values
(e.g.
display: list-item
generate more than one box
(e.g. a
principal block box
and a child
marker box
).
And some values
(such as
none
or
contents
cause the
element
and/or its descendants to not generate any
boxes
at all.
Boxes
are often referred to by their
display
type—e.g. a
box
generated by an element with
display: block
is called a “block box” or just a “block”.
box
is assigned the same styles as its generating
element
, unless otherwise indicated.
In general,
inherited properties
are assigned to the
principal box
and then inherit through the box tree
to any other boxes generated by the same element.
Non-inherited properties default to applying to the
principal box
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
table grid box
not to its
principal
table wrapper box
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
text nodes
generates a
text sequence
containing their text contents,
which is assigned the same styles as the generating
text nodes
If the sequence contains no text, however, it does not generate a
text sequence
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
parent box
of an element’s
principal box
is the
principal box
of its nearest ancestor element that generates a
box
however, there are some exceptions,
such as for
run-in
boxes,
display types (like tables) that generate multiple container boxes,
and intervening
anonymous boxes
An
anonymous box
is a box that is not associated with any element.
Anonymous boxes
are generated in certain circumstances
to fix up the
box tree
when it requires a particular nested structure
that is not provided by the boxes generated from the
element tree
For example, a
table cell box
requires a particular type of parent box (the
table row box
),
and will generate an
anonymous
table row box
around itself
if its parent is not a
table row box
(See
[CSS2]
17.2.1
.)
Unlike element-generated boxes, whose styles inherit strictly through the element tree,
anonymous boxes (which only exist in the
box tree
inherit
through their
box tree
parentage.
In the course of layout,
boxes
and
text sequences
can be broken into multiple
fragments
This happens, for example, when an
inline box
and/or
text sequence
is broken across lines,
or when a
block box
is broken across pages or columns,
in a process called
fragmentation
It can also happen due to bidi reordering of text
(see
Applying the Bidirectional Reordering Algorithm
in
CSS Writing Modes
or higher-level
display type
box splitting,
e.g.
block-in-inline splitting
(see
CSS2§9.2
or
column-spanner-in-block
splitting
(see
CSS Multi-column Layout
).
box
therefore consists of one or more
box fragments
and a
text sequence
consists of one or more
text fragments
See
[CSS-BREAK-3]
for more information on
fragmentation
Note:
Many of the CSS specs were written before this terminology was ironed out,
or refer to things incorrectly,
so view older specs with caution when they’re using these terms.
It should be possible to infer from context which term they really mean.
Please
report errors
in specs when you find them,
so they can be corrected.
Note:
Further information on the “aural” box tree
and its interaction with the
display
property
can be found in the
CSS Speech Module
[CSS-SPEECH-1]
Tests
empty-text-baseline-001.html
(live test)
(source)
empty-text-baseline-002.html
(live test)
(source)
1.1.
Module interactions
This module replaces and extends the definition of the
display
property defined in
[CSS2]
section 9.2.4.
None of the properties in this module apply to the
::first-line
or
::first-letter
pseudo-elements.
Tests
display-first-letter-001.html
(live test)
(source)
display-first-line-001.html
(live test)
(source)
display-first-line-002.html
(live test)
(source)
display-inline-dynamic-001.html
(live test)
(source)
1.2.
Value Definitions
This specification follows the
CSS property definition conventions
from
[CSS2]
using the
value definition syntax
from
[CSS-VALUES-3]
Value types not defined in this specification are defined in CSS Values & 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
CSS-wide keywords
as their property value.
For readability they have not been repeated explicitly.
2.
Box Layout Modes: the
display
property
Name:
display
Value:
||
Initial:
inline
Applies to:
all elements
Inherited:
no
Percentages:
n/a
Computed value:
a pair of keywords representing the
inner
and
outer
display types plus optional
list-item
flag, or a
or
keyword; see prose in a variety of specs for computation rules
Canonical order:
per grammar
Animation type:
see
§ 2.9 Animating and Interpolating display
User agents are expected to support this property on all media, including non-visual ones.
The
display
property defines an element’s
display type
which consists of the two basic qualities of how an element generates boxes:
the
inner display type
which defines (if it is a
non-replaced element
) the kind of
formatting context
it generates,
dictating how its descendant boxes are laid out.
(The inner display of a
replaced element
is outside the scope of CSS.)
the
outer display type
which dictates how the
principal box
itself participates in
flow layout
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
none
, which causes the element’s entire subtree to be left out of the box tree.
The
display
property has no effect on an element’s semantics:
these are defined by the
document language
and
are not affected by CSS
Aside from the
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
without
affecting the underlying document semantics.
Values are defined as follows:
= block
inline
run-in
= flow
flow-root
table
flex
grid
ruby
&&
[ flow
flow-root ]
&&
list-item
= 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
= contents
none
= inline-block
inline-table
inline-flex
inline-grid
The following informative table summarizes the values of
display
Short
display
Full
display
Generated box
none
subtree omitted from
box tree
contents
element replaced by contents in
box tree
block
block flow
block-level
block container
aka
block box
flow-root
block flow-root
block-level
block container
that establishes a new
block formatting context
BFC
inline
inline flow
inline box
inline-block
inline flow-root
inline-level
block container
aka
inline block
run-in
run-in flow
run-in box
inline box
with special box-tree-munging rules)
list-item
block flow list-item
block box
with additional
marker box
inline list-item
inline flow list-item
inline box
with additional
marker box
flex
block flex
block-level
flex container
inline-flex
inline flex
inline-level
flex container
grid
block grid
block-level
grid container
inline-grid
inline grid
inline-level
grid container
ruby
inline ruby
inline-level
ruby container
block ruby
block ruby
block box
containing
ruby container
table
block table
block-level
table wrapper box
containing
table grid box
inline-table
inline table
inline-level
table wrapper box
containing
table grid box
types
layout-specific internal box
Note:
Following the precedence rules of “most backwards-compatible, then shortest”,
serialization of equivalent
display
values uses the “Short
display
” column.
[CSSOM]
Tests
display-interpolation.html
(live test)
(source)
display-math-on-non-mathml-elements.html
(live test)
(source)
display-math-on-pseudo-elements-001.html
(live test)
(source)
display-math-on-pseudo-elements-002.html
(live test)
(source)
display-none-root-hit-test-crash.html
(live test)
(source)
inheritance.html
(live test)
(source)
display-computed.html
(live test)
(source)
display-invalid.html
(live test)
(source)
display-valid.html
(live test)
(source)
select-4-option-optgroup-display-none.html
(live test)
(source)
textarea-display.html
(live test)
(source)
2.1.
Outer Display Roles for Flow Layout: the
block
inline
, and
run-in
keywords
The
keywords specify the element’s
outer display type
which is essentially its
principal box’s
role in
flow layout
They are defined as follows:
block
The element generates a box that is
block-level
when placed in
flow layout
[CSS2]
inline
The element generates a box that is
inline-level
when placed in
flow layout
[CSS2]
run-in
The element generates an
run-in box
which is a type of
inline-level box
with special behavior that attempts to merge it into a subsequent block container.
See
§ 6 Run-In Layout
for details.
Note:
Outer display types
do affect
replaced elements
If a
value is specified but
is omitted,
the element’s
inner display type
defaults to
flow
Tests
display-change-iframe.html
(live test)
(source)
display-change-object-iframe.html
(live test)
(source)
after-content-display-004.xht (visual test)
(source)
anonymous-box-generation-002.xht (visual test)
(source)
background-applies-to-011.xht (visual test)
(source)
background-attachment-applies-to-011.xht (visual test)
(source)
background-color-applies-to-011.xht (visual test)
(source)
background-image-applies-to-011.xht (visual test)
(source)
background-position-applies-to-011.xht (visual test)
(source)
background-repeat-applies-to-011.xht (visual test)
(source)
before-content-display-004.xht (visual test)
(source)
border-applies-to-011.xht (visual test)
(source)
border-bottom-applies-to-011.xht (visual test)
(source)
border-bottom-color-applies-to-011.xht (visual test)
(source)
border-bottom-style-applies-to-011.xht (visual test)
(source)
border-bottom-width-applies-to-011.xht (visual test)
(source)
border-collapse-applies-to-004.xht (visual test)
(source)
border-color-applies-to-011.xht (visual test)
(source)
border-left-applies-to-011.xht (visual test)
(source)
border-left-color-applies-to-011.xht (visual test)
(source)
border-left-style-applies-to-011.xht (visual test)
(source)
border-left-width-applies-to-011.xht (visual test)
(source)
border-right-applies-to-011.xht (visual test)
(source)
border-right-color-applies-to-011.xht (visual test)
(source)
border-right-style-applies-to-011.xht (visual test)
(source)
border-right-width-applies-to-011.xht (visual test)
(source)
border-spacing-applies-to-004.xht (visual test)
(source)
border-style-applies-to-011.xht (visual test)
(source)
border-top-applies-to-011.xht (visual test)
(source)
border-top-color-applies-to-011.xht (visual test)
(source)
border-top-style-applies-to-011.xht (visual test)
(source)
border-top-width-applies-to-011.xht (visual test)
(source)
border-width-applies-to-011.xht (visual test)
(source)
bottom-applies-to-011.xht (visual test)
(source)
caption-side-applies-to-004.xht (visual test)
(source)
clear-applies-to-011.xht (visual test)
(source)
clear-runin-001.xht (visual test)
(source)
color-applies-to-011.xht (visual test)
(source)
counter-increment-applies-to-011.xht
(live test)
(source)
counter-reset-applies-to-011.xht
(live test)
(source)
cursor-applies-to-011.xht (manual test)
(source)
direction-applies-to-011.xht (visual test)
(source)
display-004.xht (visual test)
(source)
empty-cells-applies-to-004.xht (visual test)
(source)
first-line-pseudo-009.xht (visual test)
(source)
float-applies-to-011.xht (visual test)
(source)
font-applies-to-004.xht (visual test)
(source)
font-family-applies-to-004.xht (visual test)
(source)
font-size-applies-to-004.xht (visual test)
(source)
font-style-applies-to-004.xht
(live test)
(source)
font-variant-applies-to-004.xht
(live test)
(source)
font-weight-applies-to-004.xht
(live test)
(source)
height-applies-to-011.xht
(live test)
(source)
left-applies-to-011.xht (visual test)
(source)
letter-spacing-applies-to-004.xht
(live test)
(source)
line-height-applies-to-011.xht (visual test)
(source)
list-style-applies-to-011.xht
(live test)
(source)
list-style-image-applies-to-011.xht (visual test)
(source)
list-style-position-applies-to-011.xht (visual test)
(source)
list-style-type-applies-to-011.xht
(live test)
(source)
margin-applies-to-011.xht (visual test)
(source)
margin-bottom-applies-to-011.xht (visual test)
(source)
margin-left-applies-to-011.xht (visual test)
(source)
margin-right-applies-to-011.xht (visual test)
(source)
margin-top-applies-to-011.xht (visual test)
(source)
max-height-applies-to-011.xht
(live test)
(source)
max-width-applies-to-011.xht
(live test)
(source)
min-height-applies-to-011.xht
(live test)
(source)
min-width-applies-to-011.xht
(live test)
(source)
outline-applies-to-011.xht (visual test)
(source)
outline-color-applies-to-011.xht (visual test)
(source)
outline-style-applies-to-011.xht (visual test)
(source)
outline-width-applies-to-011.xht (visual test)
(source)
overflow-applies-to-011.xht (visual test)
(source)
padding-applies-to-011.xht (visual test)
(source)
padding-bottom-applies-to-011.xht (visual test)
(source)
padding-left-applies-to-011.xht (visual test)
(source)
padding-right-applies-to-011.xht (visual test)
(source)
padding-top-applies-to-011.xht (visual test)
(source)
position-applies-to-011.xht (visual test)
(source)
quotes-applies-to-011.xht
(live test)
(source)
right-applies-to-011.xht (visual test)
(source)
run-in-001.xht (visual test)
(source)
run-in-002.xht (visual test)
(source)
run-in-003.xht (visual test)
(source)
run-in-004.xht (visual test)
(source)
run-in-005.xht (visual test)
(source)
run-in-006.xht (visual test)
(source)
run-in-007.xht (visual test)
(source)
run-in-008.xht (visual test)
(source)
run-in-009.xht (visual test)
(source)
run-in-010.xht (visual test)
(source)
run-in-011.xht (visual test)
(source)
run-in-012.xht (visual test)
(source)
run-in-013.xht (visual test)
(source)
run-in-abspos-between-001.xht
(live test)
(source)
run-in-abspos-between-002.xht
(live test)
(source)
run-in-abspos-between-003.xht
(live test)
(source)
run-in-basic-001.xht
(live test)
(source)
run-in-basic-002.xht
(live test)
(source)
run-in-basic-003.xht
(live test)
(source)
run-in-basic-004.xht
(live test)
(source)
run-in-basic-005.xht
(live test)
(source)
run-in-basic-006.xht
(live test)
(source)
run-in-basic-007.xht
(live test)
(source)
run-in-basic-008.xht
(live test)
(source)
run-in-basic-009.xht
(live test)
(source)
run-in-basic-010.xht
(live test)
(source)
run-in-basic-011.xht
(live test)
(source)
run-in-basic-012.xht
(live test)
(source)
run-in-basic-013.xht
(live test)
(source)
run-in-basic-014.xht
(live test)
(source)
run-in-basic-015.xht
(live test)
(source)
run-in-basic-016.xht
(live test)
(source)
run-in-basic-017.xht
(live test)
(source)
run-in-basic-018.xht
(live test)
(source)
run-in-block-between-001.xht
(live test)
(source)
run-in-block-between-002.xht
(live test)
(source)
run-in-block-between-003.xht
(live test)
(source)
run-in-breaking-001.xht
(live test)
(source)
run-in-breaking-002.xht
(live test)
(source)
run-in-clear-001.xht
(live test)
(source)
run-in-clear-002.xht
(live test)
(source)
run-in-contains-abspos-001.xht
(live test)
(source)
run-in-contains-block-001.xht
(live test)
(source)
run-in-contains-block-002.xht
(live test)
(source)
run-in-contains-block-003.xht
(live test)
(source)
run-in-contains-block-004.xht
(live test)
(source)
run-in-contains-block-005.xht
(live test)
(source)
run-in-contains-block-inside-inline-001.xht
(live test)
(source)
run-in-contains-block-inside-inline-002.xht
(live test)
(source)
run-in-contains-block-inside-inline-003.xht
(live test)
(source)
run-in-contains-float-001.xht
(live test)
(source)
run-in-contains-inline-001.xht
(live test)
(source)
run-in-contains-inline-002.xht
(live test)
(source)
run-in-contains-inline-003.xht
(live test)
(source)
run-in-contains-inline-004.xht
(live test)
(source)
run-in-contains-inline-005.xht
(live test)
(source)
run-in-contains-inline-006.xht
(live test)
(source)
run-in-contains-inline-007.xht
(live test)
(source)
run-in-contains-inline-block-001.xht
(live test)
(source)
run-in-contains-inline-table-001.xht
(live test)
(source)
run-in-contains-relpos-block-001.xht
(live test)
(source)
run-in-contains-relpos-block-002.xht
(live test)
(source)
run-in-contains-relpos-block-003.xht
(live test)
(source)
run-in-contains-run-in-001.xht
(live test)
(source)
run-in-contains-run-in-002.xht
(live test)
(source)
run-in-contains-run-in-003.xht
(live test)
(source)
run-in-contains-table-001.xht
(live test)
(source)
run-in-contains-table-002.xht
(live test)
(source)
run-in-contains-table-003.xht
(live test)
(source)
run-in-contains-table-caption-001.xht
(live test)
(source)
run-in-contains-table-cell-001.xht
(live test)
(source)
run-in-contains-table-column-001.xht
(live test)
(source)
run-in-contains-table-column-group-001.xht
(live test)
(source)
run-in-contains-table-inside-inline-001.xht
(live test)
(source)
run-in-contains-table-inside-inline-002.xht
(live test)
(source)
run-in-contains-table-inside-inline-003.xht
(live test)
(source)
run-in-contains-table-row-001.xht
(live test)
(source)
run-in-contains-table-row-group-001.xht
(live test)
(source)
run-in-display-none-between-001.xht
(live test)
(source)
run-in-display-none-between-002.xht
(live test)
(source)
run-in-display-none-between-003.xht
(live test)
(source)
run-in-fixedpos-between-001.xht
(live test)
(source)
run-in-fixedpos-between-002.xht
(live test)
(source)
run-in-fixedpos-between-003.xht
(live test)
(source)
run-in-float-between-001.xht
(live test)
(source)
run-in-float-between-002.xht
(live test)
(source)
run-in-float-between-003.xht
(live test)
(source)
run-in-inherit-001.xht
(live test)
(source)
run-in-inheritance-001.xht (visual test)
(source)
run-in-inline-between-001.xht
(live test)
(source)
run-in-inline-between-002.xht
(live test)
(source)
run-in-inline-between-003.xht
(live test)
(source)
run-in-inline-block-between-001.xht
(live test)
(source)
run-in-inline-block-between-002.xht
(live test)
(source)
run-in-inline-block-between-003.xht
(live test)
(source)
run-in-inline-table-between-001.xht
(live test)
(source)
run-in-inline-table-between-002.xht
(live test)
(source)
run-in-inline-table-between-003.xht
(live test)
(source)
run-in-linebox-001.xht (visual test)
(source)
run-in-linebox-002.xht (visual test)
(source)
run-in-listitem-between-001.xht
(live test)
(source)
run-in-listitem-between-002.xht
(live test)
(source)
run-in-listitem-between-003.xht
(live test)
(source)
run-in-relpos-between-001.xht
(live test)
(source)
run-in-relpos-between-002.xht
(live test)
(source)
run-in-relpos-between-003.xht
(live test)
(source)
run-in-replaced-001.xht
(live test)
(source)
run-in-restyle-001.xht
(live test)
(source)
run-in-restyle-002.xht
(live test)
(source)
run-in-restyle-003.xht
(live test)
(source)
run-in-run-in-between-001.xht
(live test)
(source)
run-in-run-in-between-002.xht
(live test)
(source)
run-in-run-in-between-003.xht
(live test)
(source)
run-in-run-in-between-004.xht
(live test)
(source)
run-in-run-in-between-005.xht
(live test)
(source)
run-in-run-in-between-006.xht
(live test)
(source)
run-in-run-in-between-007.xht
(live test)
(source)
run-in-run-in-between-008.xht
(live test)
(source)
run-in-table-between-001.xht
(live test)
(source)
run-in-table-between-002.xht
(live test)
(source)
run-in-table-between-003.xht
(live test)
(source)
run-in-table-cell-between-001.xht
(live test)
(source)
run-in-table-cell-between-002.xht
(live test)
(source)
run-in-table-cell-between-003.xht
(live test)
(source)
run-in-table-row-between-001.xht
(live test)
(source)
run-in-table-row-between-002.xht
(live test)
(source)
run-in-table-row-between-003.xht
(live test)
(source)
run-in-text-between-001.xht
(live test)
(source)
run-in-text-between-002.xht
(live test)
(source)
run-in-text-between-003.xht
(live test)
(source)
run-in-text-between-004.xht
(live test)
(source)
run-in-text-between-005.xht
(live test)
(source)
table-anonymous-block-001.xht (visual test)
(source)
table-layout-applies-to-004.xht (visual test)
(source)
text-align-applies-to-004.xht (visual test)
(source)
text-decoration-applies-to-004.xht
(live test)
(source)
text-indent-applies-to-004.xht (visual test)
(source)
text-transform-applies-to-004.xht
(live test)
(source)
top-applies-to-011.xht (visual test)
(source)
unicode-bidi-applies-to-011.xht (visual test)
(source)
vertical-align-applies-to-011.xht (visual test)
(source)
visibility-applies-to-011.xht (visual test)
(source)
white-space-applies-to-004.xht (visual test)
(source)
width-applies-to-011.xht
(live test)
(source)
word-spacing-applies-to-004.xht (visual test)
(source)
z-index-applies-to-011.xht (visual test)
(source)
2.2.
Inner Display Layout Models: the
flow
flow-root
table
flex
grid
, and
ruby
keywords
The
keywords specify the element’s
inner display type
which defines the type of formatting context that lays out its contents
(assuming it is a
non-replaced element
).
They are defined as follows:
flow
The element lays out its contents using
flow layout
block-and-inline layout
).
If its
outer display type
is
inline
or
run-in
and it is participating in a
block
or
inline
formatting context,
then it generates an
inline box
Otherwise it generates a
block container
box.
Depending on the value of other properties (such as
position
float
, or
overflow
and whether it is itself participating in a block or inline
formatting context
it either establishes a new
block formatting context
for its contents
or integrates its contents into its parent
formatting context
See
CSS2.1 Chapter 9
[CSS2]
block container
that establishes a new
block formatting context
is considered to have a used
inner display type
of
flow-root
flow-root
The element generates a
block container
box,
and lays out its contents using
flow layout
It always establishes a new
block formatting context
for its contents.
[CSS2]
table
The element generates a principal
table wrapper box
that establishes a
block formatting context
and which contains
an additionally-generated
table grid box
that establishes a
table formatting context
[CSS2]
flex
The element generates a principal
flex container
box
and establishes a
flex formatting context
[CSS-FLEXBOX-1]
grid
The element generates a principal
grid container
box,
and establishes a
grid formatting context
[CSS-GRID-1]
(Grids using
subgrid
might not generate a new
grid formatting context
see
[CSS-GRID-2]
for details.)
ruby
The element generates a
ruby container
box
and establishes a
ruby formatting context
in addition to integrating its base-level contents
into its parent
formatting context
(if it is inline)
or generating a wrapper box of the appropriate
outer display type
(if it is not).
[CSS-RUBY-1]
If a
value is specified but
is omitted,
the element’s
outer display type
defaults to
block
—except for
ruby
, which defaults to
inline
Tests
display-flow-root-001.html
(live test)
(source)
display-flow-root-002.html
(live test)
(source)
display-none-inline-img.html
(live test)
(source)
2.3.
Generating Marker Boxes: the
list-item
keyword
The
list-item
keyword
causes the element to generate a
::marker
pseudo-element
[CSS-PSEUDO-4]
with the content specified by its
list-style
properties
CSS 2.1§12.5 Lists
[CSS2]
together with a principal box of the specified type for its own contents.
If no
inner display type
value is specified,
the principal box’s
inner display type
defaults to
flow
If no
outer display type
value is specified,
the principal box’s
outer display type
defaults to
block
Note:
In this level, as restricted in the grammar,
list-items are limited to the
Flow Layout
display types
block
inline
run-in
with
flow
flow-root
inner types).
This restriction may be relaxed in a future level of this module.
Tests
display-flow-root-list-item-001.html
(live test)
(source)
display-list-item-height-after-dom-change.html
(live test)
(source)
2.4.
Layout-Internal Display Types: the
table-*
and
ruby-*
keywords
Some layout models, such as
table
and
ruby
have a complex internal structure,
with several different roles that their children and descendants can fill.
This section defines those “
layout-internal
display
values,
which only have meaning within that particular layout mode.
Unless otherwise specified,
both the
inner display type
and the
outer display type
of elements using these
display
values
are set to the given keyword.
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
inline
White space collapsing and anonymous box generation must happen around those replaced elements
based on that
inline
value,
as if they never had a
layout-internal
display value applied to them.
Authors should not assign a
layout-internal
display value to
replaced elements
The
keywords are defined as follows:
table-row-group
table-header-group
table-footer-group
table-row
table-cell
table-column-group
table-column
The element is an
internal table element
It generates the appropriate
internal table box
which participates in a
table formatting context
See
CSS2§17.2
[CSS2]
table-cell
boxes have a
flow-root
inner display type
table-caption
The element generates a
table caption box
which is a
block box
with special behavior with respect to table and table wrapper boxes.
See
CSS2§17.2
[CSS2]
table-caption
boxes have a
flow-root
inner display type
ruby-base
ruby-text
ruby-base-container
ruby-text-container
The element is an
internal ruby element
It generates the appropriate
internal ruby box
which participates in a
ruby formatting context
[CSS-RUBY-1]
ruby-base
and
ruby-text
have a
flow
inner display type
Boxes with layout-specific display types generate anonymous wrapper boxes around themselves
when placed in an incompatible parent,
as defined by their respective specifications.
For example, Table Layout requires that a
table-cell
box
must have a
table-row
parent box.
If it is misparented, like so:
div
style
"display:block;"
div
style
"display:table-cell"
...
div
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 table layout has a predictable structure to operate on.
Tests
This section lacks tests.
2.5.
Box Generation: the
none
and
contents
keywords
While
display
can control the
types
of boxes an element will generate,
it can also control whether an element will generate any boxes at all.
The
keywords are defined as follows:
contents
The element itself does not generate any boxes,
but its children and pseudo-elements still generate
boxes
and
text sequences
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
inheritance
are not affected.
As of writing, however,
this is not implemented correctly in major browsers
so using this feature on the Web must be done with care
as it can prevent accessibility tools
from accessing the element’s semantics.
This value computes to
display: none
on replaced elements
and other elements whose rendering is not entirely controlled by CSS;
see
Appendix B: Effects of display: contents on Unusual Elements
for details.
Note:
Replaced elements and form controls are treated specially
because removing only the element’s own generating box
is a more-or-less undefined operation.
As this behavior may be refined if use cases
(and more precise rendering models) develop,
authors should use
display: none
rather than
display: contents
on such elements for forward-compatibility.
none
The
element
and its descendants generate no
boxes
or
text sequences
Similarly, if a
text node
is defined to behave as
display: none
it generates no
text sequences
Elements with either of these values do not have
inner
or
outer display types
because they don’t generate any boxes at all.
Note:
As these values cause affected elements to not generate a box,
anonymous box generation rules will ignore the elided elements entirely,
as if they did not exist in the box tree.
Markup-based relationships, however, are not affected by these values,
as they are solely rendering-time effects.
For example,
although they may affect which table cell
appears
in a column,
they do not affect which table cell is associated with a particular column
element
Similarly, they cannot affect which HTML
summary
element is associated with a particular table
or whether a
legend
is considered to be labelling the contents of a particular
fieldset
Tests
display-contents-role-and-label.html
(live test)
(source)
display-contents-001-crash.html
(live test)
(source)
display-contents-alignment-001.html
(live test)
(source)
display-contents-alignment-002.html
(live test)
(source)
display-contents-before-after-001.html
(live test)
(source)
display-contents-before-after-002.html
(live test)
(source)
display-contents-before-after-003.html
(live test)
(source)
display-contents-block-001.html
(live test)
(source)
display-contents-block-002.html
(live test)
(source)
display-contents-blockify-dynamic.html
(live test)
(source)
display-contents-button.html
(live test)
(source)
display-contents-computed-style.html
(live test)
(source)
display-contents-details-001.html
(live test)
(source)
display-contents-details.html
(live test)
(source)
display-contents-dynamic-before-after-001.html
(live test)
(source)
display-contents-dynamic-before-after-first-letter-001.html
(live test)
(source)
display-contents-dynamic-fieldset-legend-001.html
(live test)
(source)
display-contents-dynamic-flex-001-inline.html
(live test)
(source)
display-contents-dynamic-flex-001-none.html
(live test)
(source)
display-contents-dynamic-flex-002-inline.html
(live test)
(source)
display-contents-dynamic-flex-002-none.html
(live test)
(source)
display-contents-dynamic-flex-003-inline.html
(live test)
(source)
display-contents-dynamic-flex-003-none.html
(live test)
(source)
display-contents-dynamic-generated-content-fieldset-001.html
(live test)
(source)
display-contents-dynamic-inline-flex-001-inline.html
(live test)
(source)
display-contents-dynamic-inline-flex-001-none.html
(live test)
(source)
display-contents-dynamic-list-001-inline.html
(live test)
(source)
display-contents-dynamic-list-001-none.html
(live test)
(source)
display-contents-dynamic-multicol-001-inline.html
(live test)
(source)
display-contents-dynamic-multicol-001-none.html
(live test)
(source)
display-contents-dynamic-pseudo-insertion-001.html
(live test)
(source)
display-contents-dynamic-table-001-inline.html
(live test)
(source)
display-contents-dynamic-table-001-none.html
(live test)
(source)
display-contents-dynamic-table-002-inline.html
(live test)
(source)
display-contents-dynamic-table-002-none.html
(live test)
(source)
display-contents-fieldset-002.html
(live test)
(source)
display-contents-fieldset-nested-legend.html
(live test)
(source)
display-contents-fieldset.html
(live test)
(source)
display-contents-first-letter-001.html
(live test)
(source)
display-contents-first-letter-002.html
(live test)
(source)
display-contents-first-line-001.html
(live test)
(source)
display-contents-first-line-002.html
(live test)
(source)
display-contents-flex-001.html
(live test)
(source)
display-contents-flex-002.html
(live test)
(source)
display-contents-flex-003.html
(live test)
(source)
display-contents-float-001.html
(live test)
(source)
display-contents-focusable-001.html
(live test)
(source)
display-contents-inline-001.html
(live test)
(source)
display-contents-inline-002.html
(live test)
(source)
display-contents-inline-flex-001.html
(live test)
(source)
display-contents-line-height.html
(live test)
(source)
display-contents-list-001.html
(live test)
(source)
display-contents-multicol-001.html
(live test)
(source)
display-contents-oof-001.html
(live test)
(source)
display-contents-oof-002.html
(live test)
(source)
display-contents-parsing-001.html
(live test)
(source)
display-contents-pseudo-click-target.html
(live test)
(source)
display-contents-root-background.html
(live test)
(source)
display-contents-shadow-dom-1.html
(live test)
(source)
display-contents-shadow-host-whitespace.html
(live test)
(source)
display-contents-sharing-001.html
(live test)
(source)
display-contents-slot-attach-whitespace.html
(live test)
(source)
display-contents-state-change-001.html
(live test)
(source)
display-contents-suppression-dynamic-001.html
(live test)
(source)
display-contents-svg-anchor-child.html
(live test)
(source)
display-contents-svg-elements.html
(live test)
(source)
display-contents-svg-switch-child.html
(live test)
(source)
display-contents-table-001.html
(live test)
(source)
display-contents-table-002.html
(live test)
(source)
display-contents-td-001.html
(live test)
(source)
display-contents-text-inherit-002.html
(live test)
(source)
display-contents-text-inherit.html
(live test)
(source)
display-contents-text-only-001.html
(live test)
(source)
display-contents-tr-001.html
(live test)
(source)
display-contents-unusual-html-elements-none.html
(live test)
(source)
display-contents-whitespace-inside-inline.html
(live test)
(source)
display-contents-focus.html
(live test)
(source)
2.6.
Precomposed Inline-level Display Values
CSS level 2 used a single-keyword syntax for
display
requiring separate keywords for block-level and inline-level variants of the same layout mode.
These
keywords map as follows:
inline-block
Computes to
inline flow-root
inline-table
Computes to
inline table
inline-flex
Computes to
inline flex
inline-grid
Computes to
inline grid
Note:
Although these keywords and their equivalents compute to the same value,
their
specified values
remain distinct.
Note:
The
getComputedStyle()
serialization rules
will always output these precomposed keywords
rather than the equivalent two-keyword pairs
due to the
shortest, most backwards-compatible serialization principle
Tests
This section lacks tests.
2.7.
Automatic Box Type Transformations
Some layout effects require
blockification
or
inlinification
of the box type,
which sets the box’s
computed
outer display type
to
block
or
inline
(respectively).
(This has no effect on
display types
that generate no box at all,
such as
none
or
contents
.)
Additionally:
If a
block box
block flow
) is
inlinified
its
inner display type
is set to
flow-root
so that it remains a block container.
If an
inline box
inline flow
) 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.
For legacy reasons,
if an
inline block box
inline flow-root
is
blockified
it becomes a
block
box
(losing its
flow-root
nature).
For consistency,
run-in flow-root
box
also
blockifies
to a
block
box.
If a
layout-internal
box is
blockified
its
inner display type
converts to
flow
so that it becomes a
block container
Inlinification
has no effect on
layout-internal
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
computed value
of
display
, such as
blockification
and
inlinification
described here.
The other, taking place during
box tree construction
(after computed values have been determined),
is the creation of intermediary anonymous boxes,
such as happens in
tables
ruby
and
flow
layout.
Some examples of computed-value fixup include:
Absolute positioning or floating an element
blockifies
the box’s display type.
[CSS2]
Containment in a
ruby container
inlinifies
the box’s display type, as described in
[CSS-RUBY-1]
A parent with a
grid
or
flex
display
value
blockifies
the box’s display type.
[CSS-GRID-1]
[CSS-FLEXBOX-1]
2.8.
The Root Element’s Principal Box
The
root element
’s display type is always
blockified
and its
principal box
always establishes an
independent formatting context
This box’s
containing block
is the
initial containing block
Additionally, a
display
of
contents
computes to
block
on the root element.
2.9.
Animating and Interpolating
display
In general,
the
display
property’s
animation type
is
discrete
However,
similar to interpolation of
visibility
(see
Web Animations
§ Animation of visibility
),
during interpolation between
none
and any other
display
value,
values between 0 and 1
map to the non-
none
value.
Additionally,
the element is
inert
as long as its
display
value would compute to
none
when ignoring the Transitions and Animations
cascade origins
3.
Display Order: the
order
property
Name:
order
Value:
Initial:
Applies to:
flex items
and
grid items
Inherited:
no
Percentages:
n/a
Computed value:
specified integer
Canonical order:
per grammar
Animation type:
by computed value type
Tests
flexible-order.html
(live test)
(source)
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
§ 3.1 Reordering and 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
value,
which specifies which ordinal group the item belongs to.
Here’s an example of a catalog item card
which has a title, a photo, and a description.
Within each entry, the source document content is ordered logically
with the title first, followed by the description and the photo.
This provides a sensible ordering for speech rendering and in non-CSS browsers.
For a more compelling visual presentation, however,
order
is used to pull the image up from later in the content to the top of the card.
article.sale-item
display
flex
flex-flow
column
article.sale-item > img
order
-1
/* Shift image before other content (in layout order) */
align-self: center
article
class
"sale-item"
h1
Computer Starter Kit
h1
This is the best computer money can buy, if you don’t have much money.
ul
li
Computer
li
Monitor
li
Keyboard
li
Mouse
ul
img
src
"images/computer.jpg"
alt
"You get: a white desktop computer with matching peripherals."
width
"250"
height
"188"
article
Computer Starter Kit
This is the best computer money can buy,
if you don’t have much money.
Computer
Monitor
Keyboard
Mouse
An example rendering of the code above.
Flex
and
grid containers
lay out their contents
in
order-modified document order
starting from the lowest numbered ordinal group and going up.
Items with the same ordinal group are laid out in the order they appear in the source document.
This also affects the
painting order
[CSS2]
exactly as if the
flex
grid items
were reordered in the source document.
Absolutely-positioned children of a
flex
grid container
are treated as having
order: 0
for the purpose of determining their painting order relative to
flex
grid items
Unless otherwise specified by a future specification,
this property has no effect on boxes that are not
flex items
or
grid items
3.1.
Reordering and Accessibility
The
order
property
does not
affect ordering in non-visual media
(such as
speech
).
Likewise,
order
does not affect
the default traversal order of sequential navigation modes
(such as cycling through links, see e.g.
tabindex
[HTML]
).
Authors
must
use
order
only for spatial, not logical, reordering of content.
Style sheets that use
order
to perform logical reordering are non-conforming.
Note:
This is so that non-visual media and non-CSS UAs,
which typically present content linearly,
can rely on a logical source order,
while
order
is used to tailor the layout order.
(Since visual perception is two-dimensional and non-linear,
the desired layout order is not always logical.)
In order to preserve the author’s intended ordering in all presentation modes,
authoring tools—including WYSIWYG editors as well as Web-based authoring aids—must reorder the underlying document source
and not use
order
to perform reordering
unless the author has explicitly indicated that
the spatial order should be
out-of-sync
with
the underlying document order (which determines speech and navigation order).
For example, a tool might offer both drag-and-drop reordering of flex items
as well as handling of media queries for alternate layouts per screen size range.
Since most of the time, reordering should affect all screen ranges
as well as navigation and speech order,
the tool would perform drag-and-drop reordering at the DOM layer.
In some cases, however, the author may want different layouts per screen size.
The tool could offer this functionality by using
order
together with media queries,
but also tie the smallest screen size’s ordering to the underlying DOM order
(since this is most likely to be a logical linear presentation order)
while using
order
to define the visual presentation order in other size ranges.
This tool would be conformant, whereas a tool that only ever used
order
to handle drag-and-drop reordering
(however convenient it might be to implement it that way)
would be non-conformant.
Note:
User agents, including browsers, accessible technology, and extensions,
may offer spatial navigation features.
This section does not preclude respecting the
order
property
when determining element ordering in such spatial navigation modes;
indeed it would need to be considered for such a feature to work.
But
order
is not the only (or even the primary) CSS property
that would need to be considered for such a spatial navigation feature.
A well-implemented spatial navigation feature would need to consider
all the layout features of CSS that modify spatial relationships.
4.
Reading Order: the
reading-flow
property
reading flow container
is a block, flex or grid container
with a valid
reading-flow
value other than
normal
The
rendering-defined sibling reading flow
of a
reading flow container
is an ordered list of the children of the container.
All children must render to an element and are considered siblings in the reading flow container.
The order is determined by the
reading-flow
property.
Should this property also apply to tables?
[Issue #9922]
Name:
reading-flow
Value:
normal
source-order
flex-visual
flex-flow
grid-rows
grid-columns
grid-order
Initial:
normal
Applies to:
block, flex and grid containers
Inherited:
no
Percentages:
n/a
Computed value:
as specified
Canonical order:
per grammar
Animation type:
not animatable
The
reading-flow
property controls the order in which
elements are rendered to speech
or are navigated to when using (linear) sequential navigation methods.
It takes one keyword value. Values are defined as follows:
normal
Follow the order of elements in the DOM.
source-order
Applies to grid, flex, and block layouts.
Creates a reading flow container,
and enables the use of the
reading-order
property on direct children.
Other than respecting the
reading-order
property,
follows the order of elements in the DOM.
flex-visual
Only takes effect on flex containers.
Follows the visual reading order of flex items,
taking the writing mode into account.
Therefore, a document in English, with
flex-direction: row-reverse
and
reading-flow: flex-visual
would have a reading order of left to right.
flex-flow
Only takes effect on flex containers.
Follows the
flex-flow
direction.
grid-rows
Only takes effect on grid containers.
Follows the visual order of grid items by row,
taking the writing mode into account.
grid-columns
Only takes effect on grid containers.
Follows the visual order of grid items by column,
taking the writing mode into account.
grid-order
Only takes effect on grid containers.
Follows the
order-modified document order
Therefore, as
normal
unless the
order
property has been used to change the order of items.
In this example, there are three flex items displayed as a row,
with
reading-flow: flex-visual
and
flex-direction: row-reverse
We are in English with a text direction of left to right.
The reading order of these items is therefore
"Item 3", "Item 2", "Item 1", reading from left to right.
div
class
"wrapper"
href
"#"
Item 1
href
"#"
Item 2
href
"#"
Item 3
div
.wrapper
display
flex
flex-direction
row-reverse
reading-flow
flex-visual
In this example there are four grid items,
placed on a grid and displayed visually out of DOM order.
The
reading-flow
property has a value of
grid-rows
and the document is in English.
The reading order of these items is therefore
"Item 4", "Item 2", "Item 3", "Item 1".
div
class
"wrapper"
class
"a"
href
"#"
Item 1
class
"b"
href
"#"
Item 2
class
"c"
href
"#"
Item 3
class
"d"
href
"#"
Item 4
div
.wrapper
display
grid
grid-template-columns
repeat
150
px
);
grid-template-areas
"d b b"
"c c a"
reading-flow
grid-rows
.a
grid-area
.b
grid-area
.c
grid-area
.d
grid-area
The
reading-flow
property affects neither layout nor painting order
and therefore has no effect on rendering to the visual
canvas
When using a
flex-*
or
grid-*
keyword value,
the
order
property is taken into account.
In this example, there are three flex items displayed as a row,
with
reading-flow: flex-flow
The third item in the DOM has
order=-1
The reading order of these items is therefore
"Item 3", "Item 1", "Item 2".
div
class
"wrapper"
href
"#"
Item 1
href
"#"
Item 2
href
"#"
Item 3
div
.wrapper a:nth-child
order
-1
.wrapper
display
flex
reading-flow
flex-flow
4.1.
Overriding Reading Flow: the
reading-order
property
Name:
reading-order
Value:
Initial:
Applies to:
Direct block-level, grid item, or flex item children of a reading flow container.
Inherited:
no
Percentages:
n/a
Computed value:
specified integer
Canonical order:
per grammar
Animation type:
by computed value type
The
reading-order
property lets the author change where in the reading flow an item is visited,
overriding the position set by the
reading-flow
property on its parent.
It takes a single
value,
which specifies which ordinal group the item belongs to.
Sibling elements are ordered starting from the lowest numbered ordinal group and going up.
If the reading order of two items is equivalent, the
reading-flow
property breaks the tie.
In this example there are six grid items,
the
grid-auto-flow
property has a value of
dense
therefore items may display out of source order.
The
reading-order
property on the item with a class of
top
is
-1
Therefore Item 4 will be the first item in reading flow.
The remaining items will be visited in the order they display in rows,
as
reading-flow
has a value of
grid-rows
div
class
"wrapper"
href
"#"
Item 1
href
"#"
Item 2
href
"#"
Item 3
class
"top"
href
"#"
Item 4
href
"#"
Item 5
href
"#"
Item 6
div
.wrapper
display
grid
grid-template-columns
repeat
150
px
);
grid-auto-flow
dense
reading-flow
grid-rows
.top
reading-order
-1
In this example there are five direct block-level children of a block container
where
reading-flow
has a value of
source-order
The third item has a
reading-order
value of
-1
The reading flow visits the third item first, then the rest in source order.
div
class
"wrapper"
href
"#"
Item 1
href
"#"
Item 2
href
"#"
Item 3
href
"#"
Item 4
href
"#"
Item 5
div
.wrapper
reading-flow
source-order
.wrapper > a
display
block
.wrapper a:nth-child
){
reading-order
-1
The source document should express
the underlying logical order of elements.
The
reading-flow
and
reading-order
properties exist for cases where a given document
can have multiple reading orders depending on layout changes,
e.g. in response to
media queries
In such cases, the most common or most fundamental reading order
should be encoded in the source order
so that the document is sensical without CSS.
Design Considerations and Background
Some of the considerations that went into the design
of
reading-flow
are:
There are clear use cases for disconnecting
the reading and navigation order from the box layout order,
the most fundamental of which is to make sure
the reading and navigation order matches the
visual perception order
when it is not the same as the box layout order.
(Visual perception is non-linear, and is influenced by things like
the size, color contrast, and spacing of a visual element,
not just its spatial coordinates on the page.)
It is a
core principle of Web platform architecture
in order to allow content to be accessible to the widest possible audience
across devices that exist now and in the future,
for the underlying document to be sensical independent of CSS.
Therefore the underlying document order
should represent a logical ordering of its elements
regardless of its visual presentation.
For components of a page that do not have a strong inherent order,
a document can have multiple visual presentations with different layouts,
all conveying the same semantic information.
It should be possible for all of these presentations to have good accessibility.
Linear navigation, focus sequencing order, and screen-reader order
should always match, because there are users who use them together.
Each component or hierarchical level of a page
can have different requirements for reordering,
so CSS reordering controls should not lend themselves
too easily to blanket use
(like
box-sizing
rather than tailored use
(like
flow-relative vs. physical properties and values
).
Tests
reading-flow-computed.html
(live test)
(source)
reading-flow-invalid.html
(live test)
(source)
reading-flow-valid.html
(live test)
(source)
reading-order-computed.html
(live test)
(source)
reading-order-invalid.html
(live test)
(source)
reading-order-valid.html
(live test)
(source)
DOM needs a convenient reordering function
so that authors (even authors who don’t usually write JS)
can easily perform source order reordering when necessary
instead of misusing
order
or
reading-flow
[Issue #7387]
5.
Invisibility: the
visibility
property
Name:
visibility
Value:
visible
hidden
force-hidden
collapse
Initial:
visible
Applies to:
all elements
Inherited:
yes
Percentages:
N/A
Computed value:
as specified
Canonical order:
per grammar
Animation type:
discrete
Media:
visual
The
visibility
property specifies whether the box is rendered.
Invisible
boxes still affect layout.
(Set the
display
property to
none
to suppress box generation altogether.).
Values have the following meanings:
visible
The generated box is visible, as normal.
hidden
Any boxes generated by the element are
invisible
Descendants of the element can, however, be visible
if they have
visibility: visible
force-hidden
Any boxes generated by the element
and its descendants
are
invisible
(regardless of their
visibility
value).
collapse
Indicates that the box is
collapsed
which can cause it to take up less space than otherwise
in a formatting-context–specific way.
See
dynamic row and column effects in tables
[CSS2]
and
collapsed flex items
in flex layout
[CSS-FLEXBOX-1]
In all other cases, however,
(i.e. unless otherwise specified)
this simply makes the box
invisible
just like
hidden
Note:
Currently, many user agents and/or accessibility tools
don’t correctly implement the accessibility implications of
visible elements with semantic relationships to
invisible
elements,
so, for example,
making parent elements with special roles (such as table rows)
invisible
while leaving child elements with special roles (such as table cells) visible
can be problematic for users of those tools.
Authors should avoid creating these situations
until the tooling situation improves.
Invisible boxes
are not rendered
(as if they were fully transparent),
cannot be interacted with
(and behave as if they had
pointer-events: none
),
are removed from navigation
(similar to
display: none
),
and are also not rendered to speech
(except when
speak
is
always
[CSS-SPEECH-1]
).
However, as with
display: contents
their semantic role as a container is not affected,
to ensure that any
visible
descendants
are properly interpreted.
Note:
If
speak
is
always
an otherwise
invisible
box
is
rendered to speech,
and may be interacted with using non-visual/spatial methods.
While temporarily hiding things with
display: none
is often sufficient,
doing so removes the elements from layout entirely,
possibly causing unwanted movement or reflow of the page
when an element is hidden or shown.
visibility: hidden
can instead be used
to keep the page’s layout stable
as something is hidden and displayed.
For example,
here is a (deliberately simplified) possible implementation of a "spoiler" element
that can be revealed by clicking on the hidden text:
The symbolism earlier in the movie becomes obvious at the end,
when it's revealed that
spoiler-text
><
span
Luke is his own father
span
>spoiler-text
making the wizard's cryptic riddles meaningful.
style
spoiler-text
border-bottom
px
solid
spoiler-text
span
visibility
hidden
spoiler-text
shown
span
visibility
visible
style
script
[...
document
querySelectorAll
"spoiler-text"
)].
forEach
el
=>{
el
addEventListener
"click"
=>
el
classList
toggle
"shown"
));
});
script
This example is deliberately significantly simplified.
It is missing a number of accessibility and UX features
that a well-designed spoiler element would have
to show off the
visibility
usage more plainly.
Don’t copy this code for a real site.
Tests
This section lacks tests.
6.
Run-In Layout
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:
order and gives their meaning, or that gives the equivalent
words in a different language.
to a specific subject, text, or dialect, with explanations; a
brief dictionary.
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.
run-in box
behaves exactly as any other
inline-level box
, except:
run-in box
with a
flow
inner display type
inlinifies
its contents.
If a
run-in sequence
is immediately followed by a block box
that does not establish a new
block formatting context
it is inserted as direct children of that block box:
after its
::marker
pseudo-element’s boxes (if any),
but preceding any other boxes generated by the contents of the block
(including the box generated by the
::before
pseudo-element, if any).
This re-parenting recurses if possible
(so that the run-in effectively becomes
part of the deepest subsequent “paragraph” in its formatting context,
collecting newly-adjacent run-ins as it goes).
The reparented content is then formatted as if originally parented there.
Note that only layout is affected, not inheritance,
because property inheritance for non-anonymous boxes is based only on the element tree.
Otherwise
(if the
run-in sequence
is
not
followed by such a block),
an anonymous block box is generated around the
run-in sequence
and all immediately following inline-level content
(up to, but not including, the next
run-in sequence
, if any).
run-in sequence
is a maximal sequence of consecutive sibling
run-in boxes
and intervening
white space
and/or
out-of-flow
boxes.
Note:
This statement implies that out-of-flow boxes are reparented
if they are between two run-in boxes.
Another alternative would be to leave behind the intervening out-of-flow boxes,
or to have out-of-flow boxes impede the running-in of earlier boxes.
Implementers and authors are encouraged to contact the CSSWG if they have a preferred behavior, as this one was picked somewhat at random.
This fixup occurs before the anonymous block and inline box fixup described in
CSS2§9.2
and affects the determination of the
first formatted line
of the affected elements
as if the
run-in sequence
were originally
in its final location in the box tree.
Note:
As the earliest run-in represents the first text on the
first formatted line
of its containing block,
::first-letter
pseudo-element applied to that block element
selects the first letter of the run-in,
rather than the first letter of its own contents.
Note:
This run-in model is slightly different from the one proposed in earlier revisions of
[CSS2]
Tests
display-change-iframe.html
(live test)
(source)
display-change-object-iframe.html
(live test)
(source)
after-content-display-004.xht (visual test)
(source)
anonymous-box-generation-002.xht (visual test)
(source)
background-applies-to-011.xht (visual test)
(source)
background-attachment-applies-to-011.xht (visual test)
(source)
background-color-applies-to-011.xht (visual test)
(source)
background-image-applies-to-011.xht (visual test)
(source)
background-position-applies-to-011.xht (visual test)
(source)
background-repeat-applies-to-011.xht (visual test)
(source)
before-content-display-004.xht (visual test)
(source)
border-applies-to-011.xht (visual test)
(source)
border-bottom-applies-to-011.xht (visual test)
(source)
border-bottom-color-applies-to-011.xht (visual test)
(source)
border-bottom-style-applies-to-011.xht (visual test)
(source)
border-bottom-width-applies-to-011.xht (visual test)
(source)
border-collapse-applies-to-004.xht (visual test)
(source)
border-color-applies-to-011.xht (visual test)
(source)
border-left-applies-to-011.xht (visual test)
(source)
border-left-color-applies-to-011.xht (visual test)
(source)
border-left-style-applies-to-011.xht (visual test)
(source)
border-left-width-applies-to-011.xht (visual test)
(source)
border-right-applies-to-011.xht (visual test)
(source)
border-right-color-applies-to-011.xht (visual test)
(source)
border-right-style-applies-to-011.xht (visual test)
(source)
border-right-width-applies-to-011.xht (visual test)
(source)
border-spacing-applies-to-004.xht (visual test)
(source)
border-style-applies-to-011.xht (visual test)
(source)
border-top-applies-to-011.xht (visual test)
(source)
border-top-color-applies-to-011.xht (visual test)
(source)
border-top-style-applies-to-011.xht (visual test)
(source)
border-top-width-applies-to-011.xht (visual test)
(source)
border-width-applies-to-011.xht (visual test)
(source)
bottom-applies-to-011.xht (visual test)
(source)
caption-side-applies-to-004.xht (visual test)
(source)
clear-applies-to-011.xht (visual test)
(source)
clear-runin-001.xht (visual test)
(source)
color-applies-to-011.xht (visual test)
(source)
counter-increment-applies-to-011.xht
(live test)
(source)
counter-reset-applies-to-011.xht
(live test)
(source)
cursor-applies-to-011.xht (manual test)
(source)
direction-applies-to-011.xht (visual test)
(source)
display-004.xht (visual test)
(source)
empty-cells-applies-to-004.xht (visual test)
(source)
first-line-pseudo-009.xht (visual test)
(source)
float-applies-to-011.xht (visual test)
(source)
font-applies-to-004.xht (visual test)
(source)
font-family-applies-to-004.xht (visual test)
(source)
font-size-applies-to-004.xht (visual test)
(source)
font-style-applies-to-004.xht
(live test)
(source)
font-variant-applies-to-004.xht
(live test)
(source)
font-weight-applies-to-004.xht
(live test)
(source)
height-applies-to-011.xht
(live test)
(source)
left-applies-to-011.xht (visual test)
(source)
letter-spacing-applies-to-004.xht
(live test)
(source)
line-height-applies-to-011.xht (visual test)
(source)
list-style-applies-to-011.xht
(live test)
(source)
list-style-image-applies-to-011.xht (visual test)
(source)
list-style-position-applies-to-011.xht (visual test)
(source)
list-style-type-applies-to-011.xht
(live test)
(source)
margin-applies-to-011.xht (visual test)
(source)
margin-bottom-applies-to-011.xht (visual test)
(source)
margin-left-applies-to-011.xht (visual test)
(source)
margin-right-applies-to-011.xht (visual test)
(source)
margin-top-applies-to-011.xht (visual test)
(source)
max-height-applies-to-011.xht
(live test)
(source)
max-width-applies-to-011.xht
(live test)
(source)
min-height-applies-to-011.xht
(live test)
(source)
min-width-applies-to-011.xht
(live test)
(source)
outline-applies-to-011.xht (visual test)
(source)
outline-color-applies-to-011.xht (visual test)
(source)
outline-style-applies-to-011.xht (visual test)
(source)
outline-width-applies-to-011.xht (visual test)
(source)
overflow-applies-to-011.xht (visual test)
(source)
padding-applies-to-011.xht (visual test)
(source)
padding-bottom-applies-to-011.xht (visual test)
(source)
padding-left-applies-to-011.xht (visual test)
(source)
padding-right-applies-to-011.xht (visual test)
(source)
padding-top-applies-to-011.xht (visual test)
(source)
position-applies-to-011.xht (visual test)
(source)
quotes-applies-to-011.xht
(live test)
(source)
right-applies-to-011.xht (visual test)
(source)
run-in-001.xht (visual test)
(source)
run-in-002.xht (visual test)
(source)
run-in-003.xht (visual test)
(source)
run-in-004.xht (visual test)
(source)
run-in-005.xht (visual test)
(source)
run-in-006.xht (visual test)
(source)
run-in-007.xht (visual test)
(source)
run-in-008.xht (visual test)
(source)
run-in-009.xht (visual test)
(source)
run-in-010.xht (visual test)
(source)
run-in-011.xht (visual test)
(source)
run-in-012.xht (visual test)
(source)
run-in-013.xht (visual test)
(source)
run-in-abspos-between-001.xht
(live test)
(source)
run-in-abspos-between-002.xht
(live test)
(source)
run-in-abspos-between-003.xht
(live test)
(source)
run-in-basic-001.xht
(live test)
(source)
run-in-basic-002.xht
(live test)
(source)
run-in-basic-003.xht
(live test)
(source)
run-in-basic-004.xht
(live test)
(source)
run-in-basic-005.xht
(live test)
(source)
run-in-basic-006.xht
(live test)
(source)
run-in-basic-007.xht
(live test)
(source)
run-in-basic-008.xht
(live test)
(source)
run-in-basic-009.xht
(live test)
(source)
run-in-basic-010.xht
(live test)
(source)
run-in-basic-011.xht
(live test)
(source)
run-in-basic-012.xht
(live test)
(source)
run-in-basic-013.xht
(live test)
(source)
run-in-basic-014.xht
(live test)
(source)
run-in-basic-015.xht
(live test)
(source)
run-in-basic-016.xht
(live test)
(source)
run-in-basic-017.xht
(live test)
(source)
run-in-basic-018.xht
(live test)
(source)
run-in-block-between-001.xht
(live test)
(source)
run-in-block-between-002.xht
(live test)
(source)
run-in-block-between-003.xht
(live test)
(source)
run-in-breaking-001.xht
(live test)
(source)
run-in-breaking-002.xht
(live test)
(source)
run-in-clear-001.xht
(live test)
(source)
run-in-clear-002.xht
(live test)
(source)
run-in-contains-abspos-001.xht
(live test)
(source)
run-in-contains-block-001.xht
(live test)
(source)
run-in-contains-block-002.xht
(live test)
(source)
run-in-contains-block-003.xht
(live test)
(source)
run-in-contains-block-004.xht
(live test)
(source)
run-in-contains-block-005.xht
(live test)
(source)
run-in-contains-block-inside-inline-001.xht
(live test)
(source)
run-in-contains-block-inside-inline-002.xht
(live test)
(source)
run-in-contains-block-inside-inline-003.xht
(live test)
(source)
run-in-contains-float-001.xht
(live test)
(source)
run-in-contains-inline-001.xht
(live test)
(source)
run-in-contains-inline-002.xht
(live test)
(source)
run-in-contains-inline-003.xht
(live test)
(source)
run-in-contains-inline-004.xht
(live test)
(source)
run-in-contains-inline-005.xht
(live test)
(source)
run-in-contains-inline-006.xht
(live test)
(source)
run-in-contains-inline-007.xht
(live test)
(source)
run-in-contains-inline-block-001.xht
(live test)
(source)
run-in-contains-inline-table-001.xht
(live test)
(source)
run-in-contains-relpos-block-001.xht
(live test)
(source)
run-in-contains-relpos-block-002.xht
(live test)
(source)
run-in-contains-relpos-block-003.xht
(live test)
(source)
run-in-contains-run-in-001.xht
(live test)
(source)
run-in-contains-run-in-002.xht
(live test)
(source)
run-in-contains-run-in-003.xht
(live test)
(source)
run-in-contains-table-001.xht
(live test)
(source)
run-in-contains-table-002.xht
(live test)
(source)
run-in-contains-table-003.xht
(live test)
(source)
run-in-contains-table-caption-001.xht
(live test)
(source)
run-in-contains-table-cell-001.xht
(live test)
(source)
run-in-contains-table-column-001.xht
(live test)
(source)
run-in-contains-table-column-group-001.xht
(live test)
(source)
run-in-contains-table-inside-inline-001.xht
(live test)
(source)
run-in-contains-table-inside-inline-002.xht
(live test)
(source)
run-in-contains-table-inside-inline-003.xht
(live test)
(source)
run-in-contains-table-row-001.xht
(live test)
(source)
run-in-contains-table-row-group-001.xht
(live test)
(source)
run-in-display-none-between-001.xht
(live test)
(source)
run-in-display-none-between-002.xht
(live test)
(source)
run-in-display-none-between-003.xht
(live test)
(source)
run-in-fixedpos-between-001.xht
(live test)
(source)
run-in-fixedpos-between-002.xht
(live test)
(source)
run-in-fixedpos-between-003.xht
(live test)
(source)
run-in-float-between-001.xht
(live test)
(source)
run-in-float-between-002.xht
(live test)
(source)
run-in-float-between-003.xht
(live test)
(source)
run-in-inherit-001.xht
(live test)
(source)
run-in-inheritance-001.xht (visual test)
(source)
run-in-inline-between-001.xht
(live test)
(source)
run-in-inline-between-002.xht
(live test)
(source)
run-in-inline-between-003.xht
(live test)
(source)
run-in-inline-block-between-001.xht
(live test)
(source)
run-in-inline-block-between-002.xht
(live test)
(source)
run-in-inline-block-between-003.xht
(live test)
(source)
run-in-inline-table-between-001.xht
(live test)
(source)
run-in-inline-table-between-002.xht
(live test)
(source)
run-in-inline-table-between-003.xht
(live test)
(source)
run-in-linebox-001.xht (visual test)
(source)
run-in-linebox-002.xht (visual test)
(source)
run-in-listitem-between-001.xht
(live test)
(source)
run-in-listitem-between-002.xht
(live test)
(source)
run-in-listitem-between-003.xht
(live test)
(source)
run-in-relpos-between-001.xht
(live test)
(source)
run-in-relpos-between-002.xht
(live test)
(source)
run-in-relpos-between-003.xht
(live test)
(source)
run-in-replaced-001.xht
(live test)
(source)
run-in-restyle-001.xht
(live test)
(source)
run-in-restyle-002.xht
(live test)
(source)
run-in-restyle-003.xht
(live test)
(source)
run-in-run-in-between-001.xht
(live test)
(source)
run-in-run-in-between-002.xht
(live test)
(source)
run-in-run-in-between-003.xht
(live test)
(source)
run-in-run-in-between-004.xht
(live test)
(source)
run-in-run-in-between-005.xht
(live test)
(source)
run-in-run-in-between-006.xht
(live test)
(source)
run-in-run-in-between-007.xht
(live test)
(source)
run-in-run-in-between-008.xht
(live test)
(source)
run-in-table-between-001.xht
(live test)
(source)
run-in-table-between-002.xht
(live test)
(source)
run-in-table-between-003.xht
(live test)
(source)
run-in-table-cell-between-001.xht
(live test)
(source)
run-in-table-cell-between-002.xht
(live test)
(source)
run-in-table-cell-between-003.xht
(live test)
(source)
run-in-table-row-between-001.xht
(live test)
(source)
run-in-table-row-between-002.xht
(live test)
(source)
run-in-table-row-between-003.xht
(live test)
(source)
run-in-text-between-001.xht
(live test)
(source)
run-in-text-between-002.xht
(live test)
(source)
run-in-text-between-003.xht
(live test)
(source)
run-in-text-between-004.xht
(live test)
(source)
run-in-text-between-005.xht
(live test)
(source)
table-anonymous-block-001.xht (visual test)
(source)
table-layout-applies-to-004.xht (visual test)
(source)
text-align-applies-to-004.xht (visual test)
(source)
text-decoration-applies-to-004.xht
(live test)
(source)
text-indent-applies-to-004.xht (visual test)
(source)
text-transform-applies-to-004.xht
(live test)
(source)
top-applies-to-011.xht (visual test)
(source)
unicode-bidi-applies-to-011.xht (visual test)
(source)
vertical-align-applies-to-011.xht (visual test)
(source)
visibility-applies-to-011.xht (visual test)
(source)
white-space-applies-to-004.xht (visual test)
(source)
width-applies-to-011.xht
(live test)
(source)
word-spacing-applies-to-004.xht (visual test)
(source)
z-index-applies-to-011.xht (visual test)
(source)
Appendix A: Glossary
The following terms are defined here for convenience:
root element
The
element
at the root of the
document tree
In a
document tree
produced under the DOM,
this is the
document element
in HTML it is the
html
element.
[DOM]
[HTML]
principal box
When an
element
generates one or more
boxes
one of them is the
principal box
which contains its descendant boxes and generated content,
and is also the box involved in any positioning scheme.
Some elements may generate additional boxes in addition to the principal box
(such as
list-item
elements,
which generate an additional marker box,
or
table
elements,
which generate a
principal
table wrapper box
and an additional
table grid box
).
These additional boxes are placed with respect to the principal box.
inline-level
Content that participates in inline layout.
Specifically, inline-level boxes and
text sequences
block-level
Content that participates in
block layout
Specifically, block-level boxes.
inline box
A non-replaced
inline-level
box whose
inner display type
is
flow
The contents of an inline box participate in the same inline formatting context as the inline box itself.
inline
Used as a shorthand for
inline box
or
inline-level box
where unambiguous,
or as an adjective meaning
inline-level
The latter usage is deprecated.
atomic inline
An inline-level box that is replaced (such as an image)
or that establishes a new formatting context (such as an
inline-block
or
inline-table
and cannot split across lines
(as
inline boxes
and
ruby containers
can).
Any inline-level box whose
inner display type
is not
flow
establishes a new formatting context of the specified
inner display type
block container
A block container either contains only inline-level boxes
participating in an
inline formatting context
or contains only block-level boxes
participating in a
block formatting context
(possibly generating anonymous block boxes to ensure this constraint,
as defined in
CSS2§9.2.1.1
).
A block container that contains only inline-level content
establishes a new
inline formatting context
The element then also generates a
root inline box
which wraps all of its inline content.
Note, this
root inline box
concept
effectively replaces the "anonymous inline element" concept
introduced in
CSS2§9.2.2.1
A block container establishes a new
block formatting context
if its parent formatting context is
not
block formatting context
otherwise, when participating in a
block formatting context
itself,
it either establishes a new
block formatting context
for its contents
or continues the one in which it participates,
as determined by the constraints of other properties
(such as
overflow
or
align-content
).
Note:
A block container box can both establish a block formatting context
and
an inline formatting context simultaneously.
block box
block-level box
that is also a
block container
Note:
Not all
block container
boxes are
block-level
boxes:
non-replaced
inline blocks
and non-replaced table cells,
for example, are block containers
but not block-level boxes.
Similarly, not all block-level boxes are block containers:
block-level replaced elements (
display: block
and flex containers (
display: flex
), for example,
are not block containers.
block
Used as a shorthand for
block box
block-level box
, or
block container box
where unambiguous.
replaced element
An element whose content is outside the scope of the CSS formatting model,
such as an image or embedded document.
For example, the content of the HTML
img
element
is often replaced by the image that its
src
attribute designates.
Replaced elements often have
natural dimensions
For example, a bitmap image has a natural width and a natural height specified in absolute units
(from which the natural ratio can obviously be determined).
On the other hand, other objects may not have any natural dimensions
(for example, a blank HTML document).
See
[css-images-3]
User agents may consider a
replaced element
to not have any
natural dimensions
if it is believed that those dimensions could leak sensitive information to a third party.
For example, if an HTML document changed natural size depending on the user’s bank balance,
then the UA might want to act as if that resource had no
natural dimensions
The content of replaced elements is not considered in the CSS formatting model;
however, their
natural dimensions
are used in various layout calculations.
Replaced elements always establish an
independent formatting context
non-replaced
element is one that is not
replaced
i.e. whose rendering is dictated by the CSS model.
containing block
A rectangle that forms the basis of sizing and positioning
for the
boxes
associated with it.
Notably, a
containing block
is
not a
box
(it is a rectangle),
however it is often derived from the dimensions of a
box
Each
box
is given a position with respect to its
containing block
but it is not confined by this
containing block
it can
overflow
The phrase “a box’s containing block” means
“the
containing block
in which the box lives,”
not the one it generates.
In general, the
edges
of a
box
act as the
containing block
for descendant boxes;
we say that a box “establishes”
the
containing block
for its descendants.
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
values are taken from the root element
unless otherwise specified.)
See
[CSS2]
Section 9.1.2
and
Section 10.1
and
CSS Positioned Layout 3
§ 2.1 Containing Blocks of Positioned Boxes
for details.
containing block chain
A sequence of successive
containing blocks
that form an ancestor-descendant chain
through the
containing block
relation.
For example, an
inline box
’s containing block is the content box of its closest
block container
ancestor;
if that block container is an
in-flow
block
then
its
containing block is formed by its parent
block container
if that grandparent
block container
is
absolutely positioned
then
its
containing block is the padding edges of its closest
positioned
ancestor (not necessarily its parent),
and so on up to the
initial containing block
initial containing block
The
containing block
of the
root element
The
initial containing block
establishes a
block formatting context
See
CSS2.1§10.1
for
continuous media
and
[CSS-PAGE-3]
for
paged media
for its position and dimensions.
formatting context
formatting context
is the environment
into which a set of related boxes are laid out.
Different
formatting contexts
lay out their boxes
according to different rules.
For example, a
flex formatting context
lays out boxes according to the
flex layout
rules
[CSS-FLEXBOX-1]
whereas a
block formatting context
lays out boxes according to the block-and-inline layout rules
[CSS2]
Additionally, some types of
formatting contexts
interleave and co-exist:
for example, an
inline formatting context
exists within
and interacts with the
block formatting context
of the element that establishes it,
and a
ruby container
overlays a
ruby formatting context
over the
inline formatting context
in which its
ruby base container
participates.
A box either establishes a new
independent formatting context
or continues the
formatting context
of its containing block.
In some cases,
it might additionally establish a new (non-independent) co-existing formatting context.
Unless otherwise specified, however,
establishing a new
formatting context
creates an
independent formatting context
The type of formatting context established by the box
is determined by its
inner display type
E.g. a
grid container
establishes a new
grid formatting context
ruby container
establishes a new
ruby formatting context
and a
block container
can establish a new
block formatting context
and/or a new
inline formatting context
See the
display
property.
independent formatting context
When a box establishes an independent formatting context
(whether that
formatting context
is of the same type as its parent or not),
it essentially creates a new, independent layout environment:
except through the sizing of the box itself,
the layout of its descendants is (generally)
not affected by the rules and contents of
the
formatting context
outside the box, and vice versa.
For example, in a
block formatting context
floated boxes affect the layout of surrounding boxes.
But their effects do not escape their
formatting context
the box establishing their
formatting context
grows to fully contain them,
and floats from outside that box
are not allowed to protrude into and affect the contents
inside the box.
As another example, margins do not collapse across
formatting context
boundaries.
Exclusions are able to affect content across
independent formatting context
boundaries.
(At time of writing, they are the only layout feature that can.)
[CSS3-EXCLUSIONS]
Certain properties can force a box to
establish an independent formatting context
in cases where it wouldn’t ordinarily.
For example,
making a box
out-of-flow
causes it to
blockify
as well as to
establish an independent formatting context
As another example,
certain values of the
contain
property
can cause a box to
establish an independent formatting context
Turning a block into a
scroll container
will cause it to
establish an independent formatting context
however turning a
subgrid
into a
scroll container
will not—it continues to act as a subgrid,
with its contents participating in the layout of its parent
grid container
block box
that
establishes an independent formatting context
establishes a new
block formatting context
for its contents.
In most other cases,
forcing a box to
establish an independent formatting context
is a no-op—either the box already establishes an
independent formatting context
(e.g.
flex containers
),
or it’s not possible to establish a totally independent new formatting context on that type of box
(e.g. non-replaced
inline boxes
).
block formatting context
inline formatting context
Block
and
inline formatting contexts
are defined in
CSS 2.1 Section 9.4
Inline formatting contexts
exist within
(are part of their containing)
block formatting contexts
for example, line boxes belonging to the
inline formatting context
interact with floats belonging to the
block formatting context
block layout
The layout of
block-level boxes
performed within a
block formatting context
block formatting context root
block container
that establishes a new
block formatting context
BFC
Abbreviation for
block formatting context
or
block formatting context root
Has various informal definitions referring to boxes which
contain internal floats, exclude external floats, and suppress margin collapsing,
and may therefore refer specifically to one of:
block container
that establishes a new
block formatting context
for its contents
block box
(i.e. a
block-level
block container)
that establishes a
block formatting context
for its contents
(as distinguished from a block box which does not)
(very loosely) any block-level box that establishes a new
formatting context
(other than an inline formatting context)
out-of-flow
in-flow
A box is
out-of-flow
if it is
extracted from its expected position and interaction with surrounding content
and laid out using a different paradigm
outside the normal flow of content in its parent formatting context.
This occurs if the box is floated (via
float
or
absolutely positioned
(via
position
).
A box is
in-flow
if it is not
out-of-flow
Note:
Some
formatting contexts
inhibit floating,
so that an element with
float: left
is not necessarily
out-of-flow
document order
The order in which boxes or content occurs in the document
(which can be different from the order in which it appears for rendering).
For the purpose of determining the relative order of pseudo-elements,
the box-tree order is used,
see
CSS Pseudo-Elements 4
§ 4 Tree-Abiding Pseudo-elements
See
[CSS2]
Chapter 9
for a fuller definition of these terms.
Appendix B: Effects of
display: contents
on Unusual Elements
This section is (currently) non-normative.
Some elements aren’t rendered purely by CSS box concepts;
for example, replaced elements (such as
img
),
many form controls (such as
input
),
and SVG elements.
This appendix defines how they interact with
display: contents
HTML Elements
br
wbr
meter
progress
canvas
embed
object
audio
iframe
img
video
frame
frameset
input
textarea
select
display: contents
computes to
display: none
legend
Per HTML, a
legend
with
display: contents
is not a
rendered legend
so it does not have magical display behavior.
(Thus, it reacts to
display: contents
normally.)
button
details
fieldset
These elements don’t have any special behavior;
display: contents
simply removes their
principal box
and their contents render as normal.
any other HTML element
Behaves as normal for
display: contents
SVG Elements
An
svg
element that has CSS box layout
(this includes all
svg
whose parent is an HTML element,
as well as document root elements)
display: contents
computes to
display: none
All other SVG
container elements
that are also
renderable elements
SVG
text content child elements
use
display: contents
strips the element from the formatting tree,
and hoists its contents up to display in its place.
These contents include the shadow-DOM content for
use
any other SVG elements
display: contents
computes to
display: none
The intention here is that
the
display: none
behavior applies
whenever the "rendering context" inside the element
is different than the context outside of it.
If the element’s child elements would not be valid children
of the element’s parent,
you cannot simply hoist them up the formatting tree.
For example, text content and text formatting elements in SVG
require a
text
element context;
if you remove a
text
its child text content and elements are no longer valid.
For that reason,
display: contents
on
text
prevents the entire text element from being rendered.
In contrast, any valid content inside a
tspan
or
textPath
is also valid content inside the parent text formatting context,
so the hoisting behavior applies for these elements.
Similarly, if hoisting would convert the children from
non-rendered elements
(e.g., a shape inside a
pattern
or
symbol
to
rendered elements
(e.g., a shape that is a direct child of the
svg
),
that is an invalid change of rendering context.
Never-rendered container elements therefore cannot be "un-boxed"
by
display: contents
When an element is stripped from the formatting tree,
then any SVG attributes on that element
that control layout and visual formatting
are ignored when rendering the contents.
However, SVG
presentation attributes
—which map to CSS properties—continue to affect value processing and inheritance
[CSS-CASCADE-3]
thus such attributes can affect
the layout and visual formatting of the element’s descendants
by influencing the values of such properties on those descendants.
MathML Elements
For all MathML elements,
display: contents
computes to
display: none
Appendix C: Box Construction Guidelines for Spec Authors
This section is non-normative guidance for specification authors.
A box cannot be
blockified
and
inlinified
at the same time;
if such a thing would occur,
define which wins over the other.
Non-principal non-anonymous boxes can’t be
blockified
blockification affects the element’s computed values
and thus determines the type of its
principal box
Boxes which
blockify
their contents
can’t directly contain
inline-level
content;
any boxes or text sequences generated within such an element
must be
blockified
or wrapped in an
anonymous
block container
Boxes which
inlinify
their contents
can’t directly contain
block-level
boxes;
any boxes generated within such an element
must be
inline-level
Boxes that fundamentally cannot establish an
independent formatting context
(such as non-replaced inlines)
must not be asked to
establish an independent formatting context
Blockify them first,
or otherwise change their box type to one that can establish an
independent formatting context
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;
Anton Prowse,
whose relentless assault on CSS2.1 Chapter 9 forced some order out of the chaos;
and Oriol Brufau,
who teased apart dozens of fine distinctions and errors in this spec.
Honorable mentions also go to David Baron, Mats Palmgren, Ilya Streltsyn,
and Boris Zbarsky for their feedback.
Changes
Recent Changes
Significant changes since the
19 December 2024 First Public Working Draft
The
reading-order
property (
Issue 11208
Added a new
source-order
value to
reading-flow
Issue 11208
Added a new
force-hidden
value to
visibility
Issue 10182
Added Web Platform Tests coverage
Additions since Level 3
The following features were added since
CSS Display Module Level 3
The
reading-flow
property
Issue 8589
The
reading-order
property (
Issue
The ability to animate
display
The
force-hidden
value of
visibility
Privacy Considerations
This specification introduces no new privacy considerations.
Security Considerations
This specification introduces no new security considerations.
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
, like
this:
UAs MUST provide an accessible alternative.
Tests
Tests relating to the content of this specification
may be documented in “Tests” blocks like this one.
Any such block is non-normative.
Conformance classes
Conformance to this specification
is defined for three conformance classes:
style sheet
CSS
style sheet
renderer
UA
that interprets the semantics of a style sheet and renders
documents that use them.
authoring tool
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.
Implementations of Unstable and Proprietary Features
To avoid clashes with future stable CSS features,
the CSSWG recommends
following best practices
for the implementation of
unstable
features and
proprietary extensions
to CSS.
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
Questions should be directed to the
public-css-testsuite@w3.org
mailing list.
Index
Terms defined by this specification
anonymous
, in § 1
anonymous box
, in § 1
atomic inline
, in § Unnumbered section
atomic inline box
, in § Unnumbered section
BFC
, in § Unnumbered section
block
definition of
, in § Unnumbered section
value for display,
, in § 2.1
block box
, in § Unnumbered section
block container
, in § Unnumbered section
block container box
, in § Unnumbered section
block formatting context
, in § Unnumbered section
block formatting context root
, in § Unnumbered section
blockification
, in § 2.7
blockify
, in § 2.7
block layout
, in § Unnumbered section
block-level
, in § Unnumbered section
block-level box
, in § 2.1
block-level content
, in § Unnumbered section
box
, in § 1
box tree
, in § 1
collapse
, in § 5
collapsed
, in § 5
containing block
, in § Unnumbered section
containing block chain
, in § Unnumbered section
contents
, in § 2.5
display
, in § 2
, in § 2
, in § 2
, in § 2
, in § 2
, in § 2
, in § 2
display type
, in § 2
document order
, in § Unnumbered section
element
, in § 1
element tree
, in § 1
establish an independent formatting context
, in § Unnumbered section
established an independent formatting context
, in § Unnumbered section
establishes an independent formatting context
, in § Unnumbered section
establishing an independent formatting context
, in § Unnumbered section
flex
, in § 2.2
flex-flow
, in § 4
flex-visual
, in § 4
flow
, in § 2.2
flow layout
, in § 2.2
flow-root
, in § 2.2
force-hidden
, in § 5
formatting context
, in § Unnumbered section
grid
, in § 2.2
grid-columns
, in § 4
grid-order
, in § 4
grid-rows
, in § 4
hidden
, in § 5
independent formatting context
, in § Unnumbered section
in flow
, in § Unnumbered section
in-flow
, in § Unnumbered section
initial containing block
, in § Unnumbered section
inline
definition of
, in § Unnumbered section
value for display,
, in § 2.1
inline block
, in § 2
inline-block
, in § 2.6
inline block box
, in § 2
inline box
, in § Unnumbered section
inline-flex
, in § 2.6
inline formatting context
, in § Unnumbered section
inline-grid
, in § 2.6
inline-level
, in § Unnumbered section
inline-level box
, in § 2.1
inline-level content
, in § Unnumbered section
inline-table
, in § 2.6
inlinification
, in § 2.7
inlinify
, in § 2.7
inner
, in § 2
inner display type
, in § 2
value for order
, in § 3
value for reading-order
, in § 4.1
internal ruby box
, in § 2.4
internal ruby element
, in § 2.4
internal table box
, in § 2.4
internal table element
, in § 2.4
invisible
, in § 5
invisible box
, in § 5
layout-internal
, in § 2.4
list-item
, in § 2.3
none
, in § 2.5
non-replaced
, in § Unnumbered section
non-replaced element
, in § Unnumbered section
normal
, in § 4
order
, in § 3
order-modified document order
, in § 3
outer
, in § 2
outer display type
, in § 2
out of flow
, in § Unnumbered section
out-of-flow
, in § Unnumbered section
parent box
, in § 1
principal box
, in § Unnumbered section
reading-flow
, in § 4
reading flow container
, in § 4
reading-order
, in § 4.1
rendering-defined sibling reading flow
, in § 4
replaced
, in § Unnumbered section
replaced element
, in § Unnumbered section
root element
, in § Unnumbered section
ruby
, in § 2.2
ruby-base
, in § 2.4
ruby-base-container
, in § 2.4
ruby-text
, in § 2.4
ruby-text-container
, in § 2.4
run-in
definition of
, in § 6
value for display,
, in § 2.1
run-in box
, in § 6
run-in sequence
, in § 6
source-order
, in § 4
table
, in § 2.2
table-caption
, in § 2.4
table caption box
, in § 2.4
table-cell
, in § 2.4
table-column
, in § 2.4
table-column-group
, in § 2.4
table-footer-group
, in § 2.4
table-header-group
, in § 2.4
table-row
, in § 2.4
table-row-group
, in § 2.4
text node
, in § 1
text sequence
, in § 1
visibility
, in § 5
visible
, in § 5
Terms defined by reference
[CSS-ALIGN-3]
defines the following terms:
align-content
[CSS-BACKGROUNDS-3]
defines the following terms:
border
[CSS-BOX-4]
defines the following terms:
box edge
[CSS-BREAK-3]
defines the following terms:
fragment
[CSS-BREAK-4]
defines the following terms:
box fragment
fragmentation
[CSS-CASCADE-5]
defines the following terms:
computed value
inheritance
inherited property
specified value
[CSS-CASCADE-6]
defines the following terms:
cascade origin
[CSS-CONTAIN-2]
defines the following terms:
contain
[CSS-FLEXBOX-1]
defines the following terms:
flex container
flex formatting context
flex item
flex layout
flex-direction
flex-flow
[CSS-GRID-2]
defines the following terms:
dense
grid container
grid formatting context
grid item
grid-auto-flow
subgrid
subgrid
(for grid-template-rows)
[CSS-IMAGES-3]
defines the following terms:
natural dimension
[CSS-INLINE-3]
defines the following terms:
root inline box
[CSS-OVERFLOW-3]
defines the following terms:
overflow
scroll container
[CSS-POSITION-3]
defines the following terms:
absolutely position
position
top
[CSS-PSEUDO-4]
defines the following terms:
::after
::before
::first-letter
::marker
first formatted line
[CSS-RUBY-1]
defines the following terms:
ruby base container
ruby container
ruby formatting context
[CSS-SIZING-3]
defines the following terms:
box-sizing
[CSS-SPEECH-1]
defines the following terms:
always
speak
[CSS-TABLES-3]
defines the following terms:
table grid box
table wrapper box
[CSS-TEXT-4]
defines the following terms:
white space
[CSS-UI-4]
defines the following terms:
pointer-events
[CSS-VALUES-4]
defines the following terms:
&&
CSS-wide keywords
||
[CSS2]
defines the following terms:
float
[CSSOM]
defines the following terms:
getComputedStyle(elt)
[DOM]
defines the following terms:
document element
document tree
[HTML]
defines the following terms:
audio
br
button
canvas
details
embed
fieldset
frame
frameset
html
iframe
img
input
legend
meter
object
progress
rendered legend
select
src
summary
textarea
video
wbr
[MEDIAQUERIES-5]
defines the following terms:
continuous media
media query
paged media
[SELECTORS-4]
defines the following terms:
document language
pseudo-elements
[SVG2]
defines the following terms:
canvas
container element
non-rendered element
pattern
presentation attributes
renderable element
rendered element
svg
symbol
text
text content child element
textPath
tspan
use
[WEB-ANIMATIONS-1]
defines the following terms:
animation type
discrete
References
Normative References
[CSS-ALIGN-3]
Elika Etemad; Tab Atkins Jr..
CSS Box Alignment Module Level 3
. URL:
[CSS-BACKGROUNDS-3]
Elika Etemad; Brad Kemper.
CSS Backgrounds and Borders Module Level 3
. URL:
[CSS-BOX-4]
Elika Etemad.
CSS Box Model Module Level 4
. URL:
[CSS-BREAK-3]
Rossen Atanassov; Elika Etemad.
CSS Fragmentation Module Level 3
. URL:
[CSS-BREAK-4]
Rossen Atanassov; Elika Etemad.
CSS Fragmentation Module Level 4
. URL:
[CSS-CASCADE-3]
Elika Etemad; Tab Atkins Jr..
CSS Cascading and Inheritance Level 3
. URL:
[CSS-CASCADE-5]
Elika Etemad; Miriam Suzanne; Tab Atkins Jr..
CSS Cascading and Inheritance Level 5
. URL:
[CSS-CASCADE-6]
Elika Etemad; Miriam Suzanne; Tab Atkins Jr..
CSS Cascading and Inheritance Level 6
. URL:
[CSS-CONTAIN-2]
Tab Atkins Jr.; Florian Rivoal; Vladimir Levin.
CSS Containment Module Level 2
. URL:
[CSS-FLEXBOX-1]
Elika Etemad; Tab Atkins Jr.; Rossen Atanassov.
CSS Flexible Box Layout Module Level 1
. URL:
[CSS-GRID-1]
Tab Atkins Jr.; et al.
CSS Grid Layout Module Level 1
. URL:
[CSS-GRID-2]
Tab Atkins Jr.; et al.
CSS Grid Layout Module Level 2
. URL:
[CSS-IMAGES-3]
Tab Atkins Jr.; Elika Etemad; Lea Verou.
CSS Images Module Level 3
. URL:
[CSS-INLINE-3]
Elika Etemad.
CSS Inline Layout Module Level 3
. URL:
[CSS-OVERFLOW-3]
Elika Etemad; Florian Rivoal.
CSS Overflow Module Level 3
. URL:
[CSS-PAGE-3]
Elika Etemad.
CSS Paged Media Module Level 3
. URL:
[CSS-POSITION-3]
Elika Etemad; Tab Atkins Jr..
CSS Positioned Layout Module Level 3
. URL:
[CSS-PSEUDO-4]
Elika Etemad; Alan Stearns.
CSS Pseudo-Elements Module Level 4
. URL:
[CSS-RUBY-1]
Elika Etemad; et al.
CSS Ruby Annotation Layout Module Level 1
. URL:
[CSS-SPEECH-1]
Léonie Watson; Elika Etemad.
CSS Speech Module Level 1
. URL:
[CSS-TABLES-3]
Keith Cirkel.
CSS Table Module Level 3
. URL:
[CSS-TEXT-4]
Elika Etemad; et al.
CSS Text Module Level 4
. URL:
[CSS-UI-4]
Tab Atkins Jr.; Florian Rivoal.
CSS Basic User Interface Module Level 4
. URL:
[CSS-VALUES-3]
Tab Atkins Jr.; Elika Etemad.
CSS Values and Units Module Level 3
. URL:
[CSS-VALUES-4]
Tab Atkins Jr.; Elika Etemad.
CSS Values and Units Module Level 4
. URL:
[CSS-WRITING-MODES-3]
Elika Etemad; Koji Ishii.
CSS Writing Modes Level 3
. URL:
[CSS2]
Bert Bos; et al.
Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification
. URL:
[CSSOM]
Daniel Glazman; Emilio Cobos Álvarez.
CSS Object Model (CSSOM)
. URL:
[DOM]
Anne van Kesteren.
DOM Standard
. Living Standard. URL:
[HTML]
Anne van Kesteren; et al.
HTML Standard
. Living Standard. URL:
[MEDIAQUERIES-5]
Tab Atkins Jr.; et al.
Media Queries Level 5
. URL:
[RFC2119]
S. Bradner.
Key words for use in RFCs to Indicate Requirement Levels
. March 1997. Best Current Practice. URL:
[SELECTORS-4]
Elika Etemad; Tab Atkins Jr..
Selectors Level 4
. URL:
[SVG2]
Amelia Bellamy-Royds; et al.
Scalable Vector Graphics (SVG) 2
. URL:
[WEB-ANIMATIONS-1]
Brian Birtles; et al.
Web Animations
. URL:
Non-Normative References
[CSS-SIZING-3]
Tab Atkins Jr.; Elika Etemad.
CSS Box Sizing Module Level 3
. URL:
[CSS3-EXCLUSIONS]
Rossen Atanassov; Vincent Hardy; Alan Stearns.
CSS Exclusions Module Level 1
. URL:
Property Index
Name
Value
Initial
Applies to
Inh.
%ages
Animation type
Canonical order
Computed value
Media
display
[
inline
all elements
no
n/a
see
per grammar
a pair of keywords representing the inner and outer display types plus optional list-item flag, or a
order
flex items and grid items
no
n/a
by computed value type
per grammar
specified integer
reading-flow
normal | source-order | flex-visual | flex-flow | grid-rows | grid-columns | grid-order
normal
block, flex and grid containers
no
n/a
not animatable
per grammar
as specified
reading-order
Direct block-level, grid item, or flex item children of a reading flow container.
no
n/a
by computed value type
per grammar
specified integer
visibility
visible | hidden | force-hidden | collapse
visible
all elements
yes
N/A
discrete
per grammar
as specified
visual
Issues Index
Should this property also apply to tables?
[Issue #9922]
DOM needs a convenient reordering function
so that authors (even authors who don’t usually write JS)
can easily perform source order reordering when necessary
instead of misusing
order
or
reading-flow
[Issue #7387]
MDN
display-outside
In all current engines.
Firefox
1+
Safari
1+
Chrome
1+
Opera
7+
Edge
79+
Edge (Legacy)
12+
IE
4+
Firefox for Android
iOS Safari
Chrome for Android
Android WebView
Samsung Internet
Opera Mobile
10.1+
MDN
display-listitem
In all current engines.
Firefox
1+
Safari
1+
Chrome
1+
Opera
7+
Edge
79+
Edge (Legacy)
12+
IE
6+
Firefox for Android
iOS Safari
Chrome for Android
Android WebView
37+
Samsung Internet
Opera Mobile
MDN
display
In all current engines.
Firefox
1+
Safari
1+
Chrome
1+
Opera
7+
Edge
79+
Edge (Legacy)
12+
IE
4+
Firefox for Android
iOS Safari
Chrome for Android
Android WebView
37+
Samsung Internet
Opera Mobile
10.1+
MDN
order
In all current engines.
Firefox
20+
Safari
9+
Chrome
29+
Opera
12.1+
Edge
79+
Edge (Legacy)
12+
IE
11
Firefox for Android
iOS Safari
Chrome for Android
Android WebView
4.4+
Samsung Internet
Opera Mobile
12.1+
MDN
visibility
In all current engines.
Firefox
1+
Safari
1+
Chrome
1+
Opera
4+
Edge
79+
Edge (Legacy)
12+
IE
4+
Firefox for Android
iOS Safari
Chrome for Android
Android WebView
Samsung Internet
Opera Mobile
10.1+
US