Overview.bs

<h1>CSS Display Module Level 3</h1>

<pre class='metadata'>
Status: WD
Work Status: Revising
ED: https://drafts.csswg.org/css-display/
Shortname: css-display
Group: csswg
Level: 3
TR: https://www.w3.org/TR/css-display-3/
Previous Version: https://www.w3.org/TR/2015/WD-css-display-3-20151015/
Previous Version: https://www.w3.org/TR/2015/WD-css-display-3-20150721/
Previous Version: https://www.w3.org/TR/2014/WD-css-display-3-20140911/
Editor: Tab Atkins Jr., Google, http://xanthir.com/contact/
Editor: Elika J. Etemad / fantasai, Invited Expert, http://fantasai.inkedblade.net/contact, w3cid 35400
Abstract: This module describes how the CSS formatting box tree is generated from the document element tree and defines the 'display' property that controls it.
Ignored Terms: display-model, display-role, table row group box, absolutely positioned
At Risk: Application of ''::first-letter'' in the presence of run-ins
At Risk: ''display: run-in''
At Risk: All two-keyword values of 'display' and ''display: inline-list-item''
</pre>
<pre class="link-defaults">
spec:css-break-3; type:dfn; text:fragment;
spec:css22; type:property; text:overflow;
</pre>

<h2 id="intro">
Introduction</h2>

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

	CSS takes a source document, organized as a tree of <dfn lt="element|element tree">elements</dfn>,
	and renders it onto a <a href="https://www.w3.org/TR/CSS2/intro.html#canvas">canvas</a> (such as your screen, a piece of paper, or an audio stream).
	To do this, it generates an intermediary structure,
	the <dfn export>box tree</dfn>,
	which represents the formatting structure of the rendered document.
	Each <dfn export>box</dfn> represents its corresponding <a>element</a> (or <a>pseudo-element</a>)
	in space and/or time on the canvas.

	To create the <a>box tree</a>,
	CSS first uses <a href="https://www.w3.org/TR/css-cascade/">cascading and inheritance</a>,
	to assign a value for each CSS property
	to each element in the source tree.
	(See [[!CSS3-CASCADE]].)

	Then, for each element, it generates zero or more boxes
	as specified by that element's 'display' property.
	Typically, an element generates a single <a>box</a>.
	However, some 'display' values
	(e.g. ''display: list-item'')
	generate more than one box
	(e.g. a <a href="https://www.w3.org/TR/CSS2/visuren.html#principal-box">principal block box</a> and a <a href="https://www.w3.org/TR/CSS2/generate.html#lists">marker box</a>).
	And some values
	(such as ''display/none'' or ''display/contents'')
	cause the <a>element</a> and/or its descendants to not generate any <a>boxes</a> at all.
	<a>Boxes</a> are assigned the same styles as their generating <a>element</a>, unless otherwise indicated.
	They're often referred to by their 'display' type--
	e.g. a <a>box</a> generated by an element with ''display: block'' is called a “block box” or just a “block”.

	An <dfn lt="anonymous|anonymous box" export>anonymous box</dfn> is is a box that is not associated with any element.
	<a>Anonymous boxes</a> are generated in certain circumstances
	to fix up the <a>box tree</a> when it requires a particular nested structure
	that is not provided by the boxes generated from the <a>element tree</a>.
	For example, a <a href="https://www.w3.org/TR/CSS2/tables.html#table-display">table cell box</a>
	requires a particular type of parent box (the <a href="https://www.w3.org/TR/CSS2/tables.html#table-display">table row box</a>),
	and will generate an <a>anonymous</a> <a href="https://www.w3.org/TR/CSS2/tables.html#table-display">table row box</a> around itself
	if its parent is not a <a href="https://www.w3.org/TR/CSS2/tables.html#table-display">table row box</a>.
	(See [[CSS2]] &sect; <a href="https://www.w3.org/TR/CSS2/tables.html#anonymous-boxes">17.2.1</a>.)
	Unlike element-generated boxes, whose styles inherit strictly through the element tree,
	anonymous boxes (which only exist in the <a>box tree</a>)
	<a href="https://www.w3.org/TR/css-cascade/#inheriting">inherit</a> through their <a>box tree</a> parentage.

	In the course of layout,
	a <a>box</a> may be broken into multiple <a>fragments</a>.
	This happens, for example, when an inline box is broken across lines,
	or when a block box is broken across pages or columns.
	A <a>box</a> therefore consists of one or more <a>box fragments</a>.
	See [[CSS3-BREAK]] for more information on <a>fragmentation</a>.

	Note: Many of the CSS specs were written before this terminology was ironed out,
	or refer to things incorrectly,
	so view older specs with caution when they're using these terms.
	It should be possible to infer from context which term they really mean.
	Please <a href="#status">report errors</a> in specs when you find them,
	so they can be corrected.

	Note: Further information on the “aural” box tree
	and its interaction with the 'display' property
	can be found in the <a href="https://www.w3.org/TR/css3-speech/#aural-model">CSS Speech Module</a>.
	[[!CSS3-SPEECH]]

<h3 id="placement">
Module interactions</h3>

	This module replaces and extends the definition of the 'display' property defined in [[!CSS2]] section 9.2.4.

	None of the properties in this module apply to the <code>::first-line</code> or <code>::first-letter</code> pseudo-elements.

<h3 id="values">
Values</h3>

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

	In addition to the property-specific values listed in their definitions,
	all properties defined in this specification also accept the
	<a href="https://www.w3.org/TR/css3-values/#common-keywords">CSS-wide keywords</a>
	as their property value. For readability it has not been repeated explicitly.

<h2 id='the-display-properties'>
Box Layout Modes: the 'display' property</h2>

	<pre class="propdef">
	Name: display
	Value: [ <<display-outside>> || <<display-inside>> ] | <<display-listitem>> | <<display-internal>> | <<display-box>> | <<display-legacy>>
	Initial: inline
	Applies to: all elements
	Inherited: no
	Computed value: as specified
	Animatable: no
	Media: all
	</pre>

	The 'display' property defines box's <dfn export>display type</dfn>,
	which consists of the two basic qualities of how an element generates boxes:

	* the <dfn export local-lt="inner">inner display type</dfn>,
		which defines (if it a <a href="https://www.w3.org/TR/CSS2/conform.html#replaced-element">non-replaced element</a>) the kind of <a>formatting context</a> it generates,
		dictating how its descendant boxes are laid out.
		(The inner display of a <a href="https://www.w3.org/TR/CSS2/conform.html#replaced-element">replaced element</a> is outside the scope of CSS.)
	* the <dfn export local-lt="outer">outer display type</dfn>,
		which dictates how the box participates in its parent formatting context.

	Some 'display' values have additional side-effects:
	such as ''list-item'', which also generates a ''::marker'' pseudo-element,
	and ''display/none'', which causes the element's entire subtree to be left out of the box tree.

	Values are defined as follows:

	<pre class='prod'>
	<dfn>&lt;display-outside></dfn>  = block | inline | run-in ;
	<dfn>&lt;display-inside></dfn>   = flow | flow-root | table | flex | grid | ruby ;
	<dfn>&lt;display-listitem></dfn> = list-item && <<display-outside>>? && [ flow | flow-root ]?
	<dfn>&lt;display-internal></dfn> = table-row-group | table-header-group |
	                     table-footer-group | table-row | table-cell |
	                     table-column-group | table-column | table-caption |
	                     ruby-base | ruby-text | ruby-base-container |
	                     ruby-text-container ;
	<dfn>&lt;display-box></dfn>      = contents | none ;
	<dfn>&lt;display-legacy></dfn>   = inline-block | inline-list-item |
	                     inline-table | inline-flex | inline-grid ;
	</pre>

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

	<style>
		#display-value-summary td,
		#display-value-summary th { text-align: left; }
	</style>
	<table class='data' id="display-value-summary">
		<thead>
			<tr>
				<th>Short 'display'
				<th>Full 'display'
				<th>Generated box
		<tbody title="Box Suppression Display Types">
			<tr>
				<td>''display/none''
				<td>&#x3003;
				<td>subtree omitted from <a>box tree</a>
			<tr>
				<td>''display/contents''
				<td>&#x3003;
				<td>element replaced by contents in <a>box tree</a>
		<tbody title="Flow Layout Display Types">
			<tr>
				<td>''block''
				<td>''block flow''
				<td><a>block-level</a> <a>block container</a>
				    <abbr title="also known as">aka</abbr> <a>block box</a>
			<tr>
				<td>''flow-root''
				<td>''block flow-root''
				<td><a>block-level</a> <a>block container</a>
				    that establishes a new <a>block formatting context</a> (<a>BFC</a>)
			<tr>
				<td>''inline''
				<td>''inline flow''
				<td><a>inline box</a>
			<tr>
				<td>''inline-block''
				<td>''inline flow-root''
				<td><a>inline-level</a> <a>block container</a>
			<tr>
				<td>''run-in''
				<td>''run-in flow''
				<td><a>run-in box</a> (<a>inline box</a> with special box-tree-munging rules)
			<tr>
				<td>''list-item''
				<td>''list-item block flow''
				<td><a>block box</a>
				    with additional <a href="https://www.w3.org/TR/CSS2/generate.html#lists">marker box</a>
			<tr>
				<td>''inline-list-item''
				<td>''list-item inline flow''
				<td><a>inline box</a>
				    with additional <a href="https://www.w3.org/TR/CSS2/generate.html#lists">marker box</a>
		<tbody title="Formatting Context Root Display Types">
			<tr>
				<td>''flex''
				<td>''block flex''
				<td><a>block-level</a> <a>flex container</a>
			<tr>
				<td>''inline-flex''
				<td>''inline flex''
				<td><a>inline-level</a> <a>flex container</a>
			<tr>
				<td>''grid''
				<td>''block grid''
				<td><a>block-level</a> <a>grid container</a>
			<tr>
				<td>''inline-grid''
				<td>''inline grid''
				<td><a>inline-level</a> <a>grid container</a>
			<tr>
				<td>''ruby''
				<td>''inline ruby''
				<td><a>inline-level</a> <a>ruby container</a>
			<tr>
				<td>''block ruby''
				<td>''block ruby''
				<td><a>block box</a> containing <a>ruby container</a>
			<tr>
				<td>''table''
				<td>''block table''
				<td><a>block-level</a> <i>table wrapper box</i> containing <i>table box</i>
			<tr>
				<td>''inline-table''
				<td>''inline table''
				<td><a>inline-level</a> <i>table wrapper box</i> containing <i>table box</i>
		<tbody title="Layout-internal display types">
			<tr>
				<td>''table-cell''
				<td>''table-cell flow-root''
				<td>table cell <a>block container</a>
			<tr>
				<td>''table-caption''
				<td>''table-caption flow-root''
				<td>table cell <a>block container</a>
			<tr>
				<td>''ruby-base''
				<td>''ruby-base flow''
				<td><a href="#layout-specific-display">layout-specific internal box</a>
			<tr>
				<td>''ruby-text''
				<td>''ruby-text flow''
				<td><a href="#layout-specific-display">layout-specific internal box</a>
			<tr>
				<td>other <<display-internal>>
				<td>&#x3003;
				<td><a href="#layout-specific-display">layout-specific internal box</a>
	</table>

	Note: Following the precedence rules of “most backwards-compatible, then shortest”,
	serialization of equivalent 'display' values uses the “Short 'display'” column.
	[[CSSOM]]

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

	The <<display-outside>> keywords specify the element's <a>outer display type</a>,
	which is essentially its role in <a>flow layout</a>.
	They are defined as follows:

	<dl dfn-type="value" dfn-for="display, <display-outside>">
		<dt><dfn>block</dfn>
		<dd>
			The element generates a <dfn dfn>block-level box</dfn>. [[!CSS2]]

		<dt><dfn>inline</dfn>
		<dd>
			The element generates an <dfn dfn>inline-level box</dfn>. [[!CSS2]]

		<dt><dfn>run-in</dfn>
		<dd>
			The element generates a <a>run-in box</a>.
			Run-in elements act like inlines or blocks,
			depending on the surrounding elements.
			See [[#run-in-layout]] for details.
	</dl>

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

<h3 id="inner-model">
Inner Display Layout Models: the ''flow'', ''flow-root'', ''table'', ''grid'', and ''ruby'' keywords</h3>

	The <<display-inside>> keywords specify the element's <a>inner display type</a>,
	which defines the type of formatting context that lays out its contents
	(assuming it is a <a href="https://www.w3.org/TR/CSS2/conform.html#replaced-element">non-replaced</a> element).
	They are defined as follows:

	<dl dfn-type="value" dfn-for="display, <display-inside>">
		<dt><dfn>flow</dfn>
		<dd>
			The element lays out its contents using <dfn dfn>flow layout</dfn>
			(<a href="https://www.w3.org/TR/CSS2/visuren.html">block-and-inline layout</a>).

			If its <a>outer display type</a> is ''inline'' or ''run-in'',
			and it is participating in a
			<a lt="block formatting context">block</a>
			or <a lt="inline formatting context">inline</a>
			formatting context,
			then it generates an <a>inline box</a>.

			Otherwise it generates a <a>block container</a> box.

			Depending on the value of other properties (such as 'position', 'float', or 'overflow')
			and whether it is itself participating in a block or inline <a>formatting context</a>,
			it either establishes a new <a>block formatting context</a> for its contents
			or integrates its contents into its parent <a>formatting context</a>.
			See <a href="https://www.w3.org/TR/CSS2/visuren.html">CSS2.1 Chapter 9</a>. [[!CSS2]]

		<dt><dfn>flow-root</dfn>
		<dd>
			The element generates a <a>block container</a> box,
			and lays out its contents using <a>flow layout</a>.
			It always establishes a new <a>block formatting context</a> for its contents. [[!CSS2]]

		<dt><dfn>table</dfn>
		<dd>
			The element generates a principal <i>table wrapper box</i>
			containing an additionally-generated <i>table box</i>,
			and establishes a <i>table formatting context</i>. [[!CSS2]]

		<dt><dfn>flex</dfn>
		<dd>
			The element generates a principal <a>flex container</a> box
			and establishes a <a>flex formatting context</a>. [[!CSS3-FLEXBOX]]

		<dt><dfn>grid</dfn>
		<dd>
			The element generates a principal <a>grid container</a> box,
			and establishes a <a>grid formatting context</a>. [[!CSS3-GRID-LAYOUT]]

		<dt><dfn>ruby</dfn>
		<dd>
			The element generates a principal <a>ruby container</a> box,
			and establishes a <a>ruby formatting context</a>. [[!CSS3RUBY]]
	</dl>

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

<h3 id="list-items">
Generating Marker Boxes: the ''list-item'' keyword</h3>

	The <dfn value for="display, <display-list-item>">list-item</dfn> keyword
	causes the element to generate a ''::marker'' pseudo-element box [[!CSS-PSEUDO-4]]
	with the content specified by its 'list-style' properties
	(<a href="https://www.w3.org/TR/CSS2/generate.html#lists">CSS 2.1§12.5 Lists</a>) [[!CSS2]]
	together with a principal box of the specified type for its own contents.

	If no <<display-inside>> value is specified,
	the principal box's <a>inner display type</a> defaults to ''flow''.
	If no <<display-outside>> value is specified,
	the principal box's <a>outer display type</a> defaults to ''block''.

	Note: In this level, as restricted in the grammar,
	a list-item can only be a block box,
	a block formatting context root box,
	an inline box,
	or an inline-block box.
	This restriction may be relaxed in a future level of this module.

<h3 id="layout-specific-display">
Layout-Internal Display Types: the ''table-*'' and ''ruby-*'' keywords</h3>

	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 "internal" 'display' values,
	which only have meaning within that particular layout mode.

	Unless otherwise specified,
	both the <a>inner display type</a> and the <a>outer display type</a>
	of elements using these 'display' values
	are set to the given keyword.

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

	<dl dfn-type=value dfn-for="display, <display-internal>">
		<dt><dfn>table-row-group</dfn>, <dfn>table-header-group</dfn>, <dfn>table-footer-group</dfn>, <dfn>table-row</dfn>, <dfn>table-cell</dfn>, <dfn>table-column-group</dfn>, <dfn>table-column</dfn>, <dfn>table-caption</dfn>
		<dd>
			The element is an <dfn dfn>internal table element</dfn>,
			and participates in a table layout context. [[!CSS2]]

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

		<dt><dfn>ruby-base</dfn>, <dfn>ruby-text</dfn>, <dfn>ruby-base-container</dfn>, <dfn>ruby-text-container</dfn>
		<dd>
			The element is an <dfn dfn>internal ruby element</dfn>,
			and participates in a ruby layout context. [[!CSS3RUBY]]

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

	Boxes with layout-specific display types generate anonymous wrapper boxes around themselves
	when placed in an incompatible parent,
	as defined by their respective specifications.

	<div class='example'>
		For example, Table Layout requires that a ''table-cell'' box
		must have a ''table-row'' parent box.

		If it is misparented, like so:

		<pre class="lang-markup">
		&lt;div style="display:block;">
			&lt;div style="display:table-cell">...&lt;/div>
		&lt;/div>
		</pre>

		It will generate wrapper boxes around itself,
		producing a structure like:

		<pre>
		block box
		└anonymous table box
		 └anonymous table-row-group box
		  └anonymous table-row box
		   └table-cell box
		</pre>

		Even if the parent is another <a>internal table element</a>,
		if it's not the <em>correct</em> one,
		wrapper boxes will be generated.
		For example, in the following markup:

		<pre class="lang-markup">
		&lt;div style="display:table;">
			&lt;div style="display:table-row">
				&lt;div style="display:table-cell">...&lt;/div>
			&lt;/div>
		&lt;/div>
		</pre>

		Anonymous wrapper box generation will produce:

		<pre>
		table box
		└anonymous table-row-group box
		 └table-row box
		  └table-cell box
		</pre>

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

<h3 id="box-generation">
Box Generation: the ''display/none'' and ''display/contents'' keywords</h3>

	While 'display' can control the <em>types</em> of boxes an element will generate,
	it can also control whether an element will generate any boxes at all.

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

	<dl dfn-type=value dfn-for="display, <display-box>">
		<dt><dfn>contents</dfn>
		<dd>
			The element itself does not generate any boxes,
			but its children and pseudo-elements still generate boxes as normal.
			For the purposes of box generation and layout,
			the element must be treated as if it had been replaced with its children and pseudo-elements in the document tree.
			However, its ''::before'' and ''::after'' pseudo-elements still exist,
			and are parented by the element's parent's principal box along with the rest of the element's box-generating contents.

			Note: As only the box tree is affected,
			any semantics based on the document tree,
			such as selector-matching and event handling,
			are not affected.

			This value has no effect on replaced elements and form controls;
			it computes to ''inline'' exactly as if the UA style sheet had specified
			''display: inline !important'' on such elements.

		<dt><dfn>none</dfn>
		<dd>
			The element and its descendants generates no boxes.
	</dl>

	Elements with either of these values do not have <a>inner</a> or <a>outer display types</a>,
	because they don't generate any boxes at all.

	Note: As these values cause affected elements to not generate a box,
	anonymous box generation rules will ignore the elided elements entirely,
	as if they did not exist in the box tree.

	Markup-based relationships, however, are not affected by these values,
	as they are solely rendering-time effects.
	For example,
	although they may affect which table cell <em>appears</em> in a column,
	they do not affect which table cell is associated with a particular column <em>element</em>.
	Similarly, they cannot affect which HTML <{summary}> element is associated with a particular table or whether a <{legend}> is the name of a <{fieldset}>.

<h3 id='legacy-display'>
Precomposed Inline-level Display Values</h3>

	CSS level 2 used a single-keyword syntax for 'display',
	requiring separate keywords for block-level and inline-level variants of the same layout mode.
	These <<display-legacy>> keywords map as follows:

	<dl dfn-type=value dfn-for="display, <display-legacy>">
		<dt><dfn>inline-block</dfn>
		<dd>
			Behaves as ''inline flow-root''.

		<dt><dfn>inline-table</dfn>
		<dd>
			Behaves as ''inline table''.

		<dt><dfn>inline-flex</dfn>
		<dd>
			Behaves as ''inline flex''.

		<dt><dfn>inline-grid</dfn>
		<dd>
			Behaves as ''inline grid''.
	</dl>

<h3 id='transformations'>
Automatic Box Type Transformations</h3>

	Some layout effects require <dfn export lt="blockify|blockification">blockification</dfn>
	or <dfn export lt="inlinify|inlinification">inlinification</dfn> of the box type,
	which sets the box’s <a>outer display type</a>,
	if it is not ''display/none'' or ''display/contents'',
	to ''block'' or ''inline'' (respectively).

	<div class='example'>
		Some examples of this include:

		<ul>
			<li>Absolute positioning or floating an element <a>blockifies</a> the box’s display type. [[CSS2]]
			<li>Containment in a <a spec=css-ruby>ruby container</a> <a>inlinifies</a> the box’s display type, as described in [[CSS3RUBY]].
			<li>A parent with a ''grid'' or ''flex'' 'display' value <a>blockifies</a> the box’s display type. [[CSS3-GRID-LAYOUT]] [[CSS3-FLEXBOX]]
		</ul>
	</div>

	If a box with a ''flow'' <a>inner display type</a> is <a>blockified</a>,
	its <a>inner display type</a> becomes ''flow-root''.
	If a box with a ''flow'' <a>inner display type</a> is <a>inlinified</a>,
	it recursively <a>inlinifies</a> all of its in-flow children,
	so that no block-level descendants
	break up the inline formatting context in which it participates.

	The root element’s display type is always <a>blockified</a>.
	Additionally, a 'display' of ''display/contents'' computes to ''block'' on the root element.

<!--

<h2 id='box-suppress'>
Toggling Box Generation: the 'display-or-not' property</h2>

	<pre class="propdef">
	Name: display-or-not
	Value: show | discard | hide
	Initial: show
	Applies to: all elements
	Inherited: no
	Percentages: n/a
	Computed value: as specified
	Media: all
	</pre>

	The ''display: none'' value was historically used as a "toggle"
	to switch between showing and hiding an element.
	Making this reversible requires either setting up the CSS <a>cascade</a> carefully,
	or remembering what the 'display' value was before it was set to ''display/none''.
	To make this common use-case easier,
	this module introduces the separate 'display-or-not' property to do the same thing,
	so that toggling whether or not an element appears in the formatting tree
	can now be done without affecting its display type when it <em>is</em> displayed.

	Issue: This property (which needs a better name)
	along with a <css>display-type</css> (or possibly <css>display-as</css>) longhand
	which takes all values of 'display' other than ''display/none'',
	are intended to be longhands of 'display'.
	This has not yet been edited in, as this split feature is likely to be deferred to the next level
	in order to have time to thoroughly work through and accommodate the
	<a href="https://lists.w3.org/Archives/Public/www-style/2016Aug/0025.html">various use cases</a> for showing/hiding an element.

	Values have the following meanings:

	<dl dfn-type="value" dfn-for="display-or-not">
		<dt><dfn>show</dfn>
		<dd>
			The element generates boxes as normal,
			per its 'display-*' properties.

		<dt><dfn>discard</dfn>
		<dd>
			The element generates no boxes at all.

		<dt><dfn>hide</dfn>
		<dd>
			The element generates boxes as normal,
			but those boxes do not participate in layout in any way,
			and must not be displayed.

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

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

			Issue: This needs more clarity about what "layout-related" and "participates in layout" means.
			Does the box still generate anonymous boxes, etc.? How does it affect speech?
			See <a href="https://lists.w3.org/Archives/Public/www-style/2015Jun/0346.html">proposal</a>.
	</dl>

	Issue: We welcome better naming suggestions on this property.

	Issue: Please send use cases (examples of where this property or something close to it is useful and necessary)
	<a href="mailto:www-style@w3.org?subject=%5Bcss-display%5D%20box-suppres%20use%20cases">to the CSSWG</a> so that we can be sure we're designing the details of its behavior correctly.

-->

<h2 id='run-in-layout'>
Run-In Layout</h2>

	A <dfn export lt="run-in | run-in box">run-in box</dfn>
	is a box that <em>merges into</em> 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.

	<div class="example">
		For example, dictionary definitions are often formatted so that the word is inline with the definition:

		<pre>
		&lt;dl class='dict'>
			&lt;dt>dictionary
			&lt;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.
			&lt;dt>glossary
			&lt;dd>an alphabetical list of terms or words found in or relating
			    to a specific subject, text, or dialect, with explanations; a
			    brief dictionary.
		&lt;/dl>
		&lt;style>
		.dict > dt {
			display: run-in;
		}
		.dict > dt::after {
			content: ": "
		}
		&lt;/style>
		</pre>

		Which is formatted as:

		<pre>
		<b>dictionary:</b> a book that lists the words of a language
		in alphabetical order and explains their meaning.

		<b>glossary:</b> an alphabetical list of terms or words found
		in or relating to a specific subject, text, or dialect,
		with explanations; a brief dictionary.
		</pre>
	</div>

	A <a>run-in box</a> behaves exactly as an <a>inline-level box</a>, except:

	<ul>
		<li>
			If a <a>run-in sequence</a> is immediately followed by a block box
			that does not establish a new <a>formatting context</a>,
			it is inserted as direct children of the block box
			after its ''::marker'' pseudo-element's boxes (if any),
			but preceding any other boxes generates by the contents of the block
			(including the box generated by the ''::before'' pseudo-element, if any).

			The reparented content is then formatted as if originally parented there.
			<span class='note'>Note that only layout is affected, not inheritance,
			because property inheritance for non-anonymous boxes is based only on the element tree.</span>

		<li>
			Otherwise,
			an anonymous block box is generated around the <a>run-in sequence</a>
			and all immediately following inline-level content
			(up to, but not including, the next <a>run-in sequence</a>, if any).

		<li>
			A <a>run-in box</a> with a ''flow'' <a>inner display type</a> <a>inlinifies</a> its contents.
	</ul>

	A <dfn>run-in sequence</dfn> is a maximal sequence of consecutive sibling <a>run-in boxes</a>
	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.

	Note: As the earliest run-in represents the first text on the <a>first formatted line</a> 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]].

<h2 id='glossary'>
Appendix A: Glossary</h2>

	The following terms are defined here for convenience:

	<dl export>
		<dt><dfn lt="inline-level|inline-level content">inline-level</dfn>
		<dd>
			Content that participates in inline layout.
			Specifically, inline-level boxes and text.

		<dt><dfn lt="block-level|block-level content">block-level</dfn>
		<dd>
			Content that participates in block layout.
			Specifically, block-level boxes.

		<dt><dfn lt="inline|inline box">inline</dfn>
		<dd>
			A non-replaced <a>inline-level</a> box whose <a>inner display type</a> is ''flow''.
			The contents of an inline box participate in the same inline formatting context as the inline box itself.

		<dt><dfn lt="atomic inline|atomic inline box">atomic inline</dfn>
		<dd>
			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'').
			Any inline-level box whose <a>inner display type</a> is not ''flow''
			establishes a new formatting context of the specified <a>inner display type</a>.

		<dt><dfn lt="block container|block container box">block container</dfn>
		<dd>
			A box whose contents participate in a <a>block formatting context</a>.
			A block container does not necessarily establish a <em>new</em> <a>block formatting context</a>
			if its parent formatting context is also a <a>block formatting context</a>.

		<dt><dfn>block box</dfn>
		<dd>
			A <a>block-level box</a> that is also a <a>block container</a>.

		<dt><dfn>block</dfn>
		<dd>
			Used as a shorthand for <a>block box</a>, <a>block-level box</a>, or <a>block container box</a>,
			where unambiguous.

		<dt><dfn>containing block</dfn>
		<dd>
			A rectangle that forms the basis of sizing and positioning
			for the boxes associated with it
			(usually the children of the box that generated it).
			Notably, a containing block is <em>not a box</em>
			(it is a rectangle),
			however it is often derived from the dimensions of a box.
			If properties of a containing block are referenced,
			they reference the values on the box that generated the containing block.
			(For the <a>initial containing block</a>, the values are taken from the root element.)
			See [[CSS2]] <a href="https://www.w3.org/TR/CSS2/visuren.html#containing-block">Section 9.1.2</a>
			and <a href="https://www.w3.org/TR/CSS2/visudet.html#containing-block-details">Section 10.1</a> for details.

		<dt><dfn>containing block chain</dfn>
		<dd>
			A sequence of successive <a>containing blocks</a>
			that form an ancestor-descendant chain
			through the <a>containing block</a> relation.
			For example, an <a>inline box</a>’s containing block is the content box of its closest <a>block container</a> ancestor;
			if that block container is an in-flow <a>block</a>,
			then <em>its</em> containing block is formed by its parent <a>block container</a>;
			if that grandparent <a>block container</a> is <a>absolutely positioned</a>,
			then <em>its</em> containing block is the padding edges of its closest <em>positioned</em> ancestor (not necessarily its parent),
			and so on up to the <a>initial containing block</a>.

		<dt><dfn>initial containing block</dfn>
		<dd>
			The <a>containing block</a> of the root element.
			See <a href="https://www.w3.org/TR/CSS2/visudet.html#containing-block-details">CSS2.1&sect;10.1</a> for continuous media;
			and [[!CSS3PAGE]] for paged media.

		<dt><dfn>formatting context</dfn>
		<dd>
			A <a>formatting context</a> 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 <a>flex formatting context</a>
			lays out boxes according to the <a>flex layout</a> rules [[CSS3-FLEXBOX]],
			whereas a <a>block formatting context</a>
			lays out boxes according to the block-and-inline layout rules [[CSS2]].

			When a box establishes a <em>new</em> 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 the rules and contents of
			the formatting context outside the box, and vice versa.

			<p class="example">
				For example, in a <a>block formatting context</a>,
				floated boxes affect the layout of surrounding boxes.
				But their effects do not escape their <a>formatting context</a>:
				the box establishing their <a>formatting context</a> grows to fully contain them,
				and floats from outside that box
				are not allowed to protrude into and affect the contents
				inside the box.

			<p class="example">
				As another example, margins do not collapse across formatting context boundaries.

			<p class="note">
				Exclusions are able to affect content across formatting context boundaries.
				(At time of writing, they are the only layout feature that can.)
				[[CSS3-EXCLUSIONS]]

		<dt><dfn>block formatting context</dfn>
		<dt><dfn>inline formatting context</dfn>
		<dd>
			Block and inline formatting contexts are defined in
			<a href="https://www.w3.org/TR/CSS2/visuren.html#normal-flow">CSS 2.1 Section 9.4</a>.

		<dt><dfn>BFC</dfn>
		<dd>
			Informal abbreviation for <a>block formatting context</a>.
			Often used to refer to a <a>block formatting context</a> <em>root</em>,
			that is, a <a>block box</a> that establishes a new <a>block formatting context</a>
			for its contents.

		<dt><dfn>out-of-flow</dfn>
		<dt><dfn>in-flow</dfn>
		<dd>
			A box is <a>out-of-flow</a> if it is floated (via 'float')
			or absolutely-positioned (via ''absolute'' or ''position/fixed'' positioning).
			A box is <a>in-flow</a> if it not <a>out-of-flow</a>.

			Note: some formatting contexts inhibit floating,
			so that an element with ''float: left'' is not necessarily <a>out-of-flow</a>.
	</dl>

	See [[!CSS2]] <a href="https://www.w3.org/TR/CSS2/visuren.html">Chapter 9</a> for a fuller definition of these terms.

<h2 class=no-num id="acknowledgments">
Acknowledgments</h2>

	We would like to thank the many people who have attempted to separate out the disparate details of box generation over the years,
	most particularly Bert Bos,
	whose last attempt with 'display-model' and 'display-role' didn't get anywhere,
	but primed us for the current spec,
	and Anton Prowse,
	whose relentless assault on CSS2.1 Chapter 9 forced some order out of the chaos.

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

<h2 class=no-num id="changes">
Changes</h2>

	Changes since the ??? Working Draft include:
	<ul>
		<li>Deferred the <css>box-suppress/display-or-not</css> property to the next level of Display,
		in order to provide time for futher discussion of use cases.
		<li>Specified that ''display: contents'' computes to ''display: inline'' on replaced elements and form controls.
		<li>Clarified that an element’s ''::before'' and ''::after'' pseudo-elements still exist if its own box is not generated due to ''display: contents''.
		<li>Clarified that event bubbling is not affected by ''display: contents''.
		<li>Clarified interaction of run-ins with out-of-flow elements and ''::first-letter''.
		<li>Switched ''table-caption'' and ''table-cell'' to use ''flow'' as their <a>inner display type</a>, since they always form a formatting context root.
		<li>Closed off remaining issues and added at-risk list.
	</ul>

	Changes since the <a href="https://www.w3.org/TR/2015/WD-css-display-3-20150721/">21 July 2015 Working Draft</a> include:

	<ul>
		<li>Added definitions for <a>in-flow</a> and <a>out-of-flow</a> to glossary.
	</ul>

	Changes since the <a href="https://www.w3.org/TR/2014/WD-css-display-3-20140911/">11 September 2014 Working Draft</a> include:

	<ul>
		<li>Removed <css>display-inside</css>, <css>display-outside</css>, and <css>display-extras</css> longhands,
			in favor of just making 'display' multi-value.
			(This was done to impose constraints on what can be combined.
			Future levels of this specification may relax some or all of those restrictions
			if they become unnecessary or unwanted.)
		<li>Created the ''flow'' and ''flow-root'' <a>inner display types</a>
			to better express flow layout <a>display types</a>
			and to create an explicit switch for making an element a <a>BFC</a> root.
			(This should eliminate the need for hacks
			like ''::after { clear: both; }'' and ''overflow: hidden''
			that are intended to accomplish this purpose.)
	</ul>