This section is normative.
CSS takes a source document organized as a 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”.
A 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). A 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]
1.1. Module interactionsThis 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.
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 propertyUser 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
displayproperty has no effect on an element’s semantics: these are defined by the
document languageand
are not affected by CSS. Aside from the
nonevalue, which also affects the aural/speech output
[CSS-SPEECH-1]and interactivity of an element and its descendants, the
displayproperty only affects visual layout: its purpose is to allow designers freedom to change the layout behavior of an element
withoutaffecting the underlying document semantics.
Values are defined as follows:
<display-outside> = block | inline | run-in
<display-inside> = flow | flow-root | table | flex | grid | ruby
<display-listitem> = <display-outside>? && [ flow | flow-root ]? && list-item
<display-internal> = table-row-group | table-header-group |
table-footer-group | table-row | table-cell |
table-column-group | table-column | table-caption |
ruby-base | ruby-text | ruby-base-container |
ruby-text-container
<display-box> = contents | none
<display-legacy> = inline-block | inline-table | inline-flex | inline-grid
The following informative table summarizes the values of display:
Note: Following the precedence rules of “most backwards-compatible, then shortest”, serialization of equivalent display values uses the “Short display” column. [CSSOM]
2.1. Outer Display Roles for Flow Layout: the block, inline, and run-in keywordsThe <display-outside> keywords specify the element’s outer display type, which is essentially its principal box’s role in flow layout. They are defined as follows:
Note: Outer display types do affect replaced elements.
If a <display-outside> value is specified but <display-inside> is omitted, the element’s inner display type defaults to flow.
2.2. Inner Display Layout Models: the flow, flow-root, table, flex, grid, and ruby keywordsThe <display-inside> keywords specify the element’s inner display type, which defines the type of formatting context that lays out its contents (assuming it is a non-replaced element). They are defined as follows:
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] A block container that establishes a new block formatting context is considered to have a used inner display type of flow-root.
(Grids using subgrid might not generate a new grid formatting context; see [CSS-GRID-2] for details.)
If a <display-inside> value is specified but <display-outside> is omitted, the element’s outer display type defaults to block—except for ruby, which defaults to inline.
2.3. Generating Marker Boxes: the list-item keywordThe 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.
2.4. Layout-Internal Display Types: the table-* and ruby-* keywordsSome 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 <display-internal> keywords are defined as follows:
table-cell boxes have a flow-root inner display type.
table-caption boxes have a flow-root inner display type.
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-cellbox must have a
table-rowparent 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.
2.5. Box Generation: the none and contents keywordsWhile display can control the types of boxes an element will generate, it can also control whether an element will generate any boxes at all.
The <display-box> keywords are defined as follows:
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.
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.
CSS level 2 used a single-keyword syntax for display, requiring separate keywords for block-level and inline-level variants of the same layout mode. These <display-legacy> keywords map as follows:
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.
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, a 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.
2.8. The Root Element’s Principal BoxThe 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 displayIn 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, p 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 propertyBoxes 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 <integer> 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,
orderis 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>
<p>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.">
</article>
Computer Starter Kit
This is the best computer money can buy, if you don’t have much money.
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 AccessibilityThe 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 propertyA 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]
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:
In this example, there are three flex items displayed as a row, with
reading-flow: flex-visualand
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"> <a href="#">Item 1</a> <a href="#">Item 2</a> <a href="#">Item 3</a> </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-flowproperty 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"> <a class="a" href="#">Item 1</a> <a class="b" href="#">Item 2</a> <a class="c" href="#">Item 3</a> <a class="d" href="#">Item 4</a> </div>
.wrapper {
display: grid;
grid-template-columns: repeat(3, 150px);
grid-template-areas: "d b b"
"c c a";
reading-flow: grid-rows;
}
.a { grid-area: a; }
.b { grid-area: b; }
.c { grid-area: c; }
.d { grid-area: d; }
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"> <a href="#">Item 1</a> <a href="#">Item 2</a> <a href="#">Item 3</a> </div>
.wrapper a:nth-child(3) {
order: -1;
}
.wrapper {
display: flex;
reading-flow: flex-flow;
}
4.1. Overriding Reading Flow: the reading-order property
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 <integer> 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-flowproperty has a value of
dense, therefore items may display out of source order. The
reading-orderproperty on the item with a class of
topis
-1Therefore 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-flowhas a value of
grid-rows.
<div class="wrapper"> <a href="#">Item 1</a> <a href="#">Item 2</a> <a href="#">Item 3</a> <a class="top" href="#">Item 4</a> <a href="#">Item 5</a> <a href="#">Item 6</a> </div>
.wrapper {
display: grid;
grid-template-columns: repeat(3, 150px);
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-flowhas a value of
source-order. The third item has a
reading-ordervalue of
-1. The reading flow visits the third item first, then the rest in source order.
<div class="wrapper"> <a href="#">Item 1</a> <a href="#">Item 2</a> <a href="#">Item 3</a> <a href="#">Item 4</a> <a href="#">Item 5</a> </div>
.wrapper { reading-flow: source-order; }
.wrapper > a { display: block; }
.wrapper a:nth-child(3){ 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 BackgroundSome 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).
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 propertyThe 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:
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: noneis 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: hiddencan 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:
<p>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: 1px solid; }
spoiler-text > span { visibility: hidden; }
spoiler-text.shown > span { visibility: visible; }
</style>
<script>
[...document.querySelectorAll("spoiler-text")].forEach(el=>{
el.addEventListener("click", e=>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.
6. Run-In LayoutA run-in box is a box that merges into a block that comes after it, inserting itself at the beginning of that block’s inline-level content. This is useful for formatting compact headlines, definitions, and other similar things, where the appropriate DOM structure is to have a headline preceding the following prose, but the desired display is an inline headline laying out with the text.
For example, dictionary definitions are often formatted so that the word is inline with the definition:
<dl class='dict'>
<dt>dictionary
<dd>a book that lists the words of a language in alphabetical
order and gives their meaning, or that gives the equivalent
words in a different language.
<dt>glossary
<dd>an alphabetical list of terms or words found in or relating
to a specific subject, text, or dialect, with explanations; a
brief dictionary.
</dl>
<style>
.dict > dt {
display: run-in;
}
.dict > dt::after {
content: ": "
}
</style>
Which is formatted as:
dictionary: a book that lists the words of a language in alphabetical order and explains their meaning. glossary: an alphabetical list of terms or words found in or relating to a specific subject, text, or dialect, with explanations; a brief dictionary.
A run-in box behaves exactly as any other inline-level box, except:
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.
A run-in sequence is a maximal sequence of consecutive sibling run-in boxes and intervening white space and/or out-of-flow boxes.
Note: This statement implies that out-of-flow boxes are reparented if they are between two run-in boxes. Another alternative would be to leave behind the intervening out-of-flow boxes, or to have out-of-flow boxes impede the running-in of earlier boxes. Implementers and authors are encouraged to contact the CSSWG if they have a preferred behavior, as this one was picked somewhat at random.
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, a ::first-letter pseudo-element applied to that block element selects the first letter of the run-in, rather than the first letter of its own contents.
Note: This run-in model is slightly different from the one proposed in earlier revisions of [CSS2].
Appendix A: GlossaryThe following terms are defined here for convenience:
html element. [DOM] [HTML]
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.
Any inline-level box whose inner display type is not flow establishes a new formatting context of the specified inner display type.
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 a 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.
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.
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.
A non-replaced element is one that is not replaced, i.e. whose rendering is dictated by the CSS model.
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.
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, a 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.
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.
A 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).
a block container that establishes a new block formatting context for its contents
a 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)
Note: Some formatting contexts inhibit floating, so that an element with float: left is not necessarily out-of-flow.
See [CSS2] Chapter 9 for a fuller definition of these terms.
Appendix B: Effects of display: contents on Unusual ElementsThis 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 Elementsbr
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.
Behaves as normal for display: contents.
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.
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.
display: contents computes to display: none.
The intention here is that the
display: nonebehavior 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 ElementsFor all MathML elements, display: contents computes to display: none.
Appendix C: Box Construction Guidelines for Spec AuthorsThis 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.
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 ChangesSignificant changes since the 19 December 2024 First Public Working Draft:
Added a new force-hidden value to visibility. (Issue 10182)
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
This specification introduces no new privacy considerations.
Security ConsiderationsThis specification introduces no new security considerations.
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:
Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:
Note, this is an informative note.
Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <strong class="advisement">, like this: UAs MUST provide an accessible alternative.
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.
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.
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.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.3