<pre class='metadata'>

Title: CSS Table Module Level 3

Shortname: css-tables

Level: 3

Status: WD

Prepare for TR: yes

Date: 2025-12-16

Work Status: Exploring

Group: csswg

ED: https://drafts.csswg.org/css-tables-3/

TR: https://www.w3.org/TR/css-tables-3/

Previous Version: https://www.w3.org/TR/2019/WD-css-tables-3-20190727/

Previous Version: https://www.w3.org/TR/CSS2/tables.html

Repository: w3c/csswg-drafts

Warning: not ready

Editor: Keith Cirkel, Mozilla, w3cid 146197

Former Editor: François Remy, Invited Expert, w3cid 53348

Former Editor: Greg Whitworth, Microsoft, w3cid 69511

Former editor: Bert Bos, W3C

Former Editor: L. David Baron, Google https://www.google.com/, https://dbaron.org/, w3cid 15393

Former editor: Markus Mielke, Microsoft

Former editor: Saloni Mira Rai, Microsoft

Abstract: This CSS module defines a two-dimensional grid-based layout system, optimized for tabular data rendering. In the table layout model, each display node is assigned to an intersection between a set of consecutive rows and a set of consecutive columns, themselves generated from the table structure and sized according to their content.

Ignored Terms: block-level box

WPT Path Prefix: css/css-tables/

WPT Display: open

</pre>

<!-- NOTE TO SELF:

BEFORE PUBLISHING A NEW WORKING DRAFT:

- switch Status to WD

- search the w3c list archives for the wg resolution allowing to republish

- fix all the linting issues

AFTER PUBLISHING A NEW WORKING DRAFT:

- revert Status to ED

- update Previous Version to the permalink of the new version you pushed

- commit those changes to csswg-drafts

-->

<pre class=link-defaults>

spec:css2; type:property;

text:top

text:right

text:bottom

spec:css-borders-4; type:property;

text:border-image

text:border-image-source

text:border-radius

text:border-style

text:border-width

spec:css-sizing-3; type:property;

text:min-height

text:min-width

text:max-width

text:box-sizing

spec:filter-effects-1; type:property; text:filter

spec:css-display-4; type:property; text:display

</pre>

<!--

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

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

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

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

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

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

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

-->

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

<em>This section is not normative</em>

Many types of information (ex: weather readings collected over the past year)

are best visually represented in a two-axis grid

where rows represent one item of the list

(ex: a date, and the various weather properties measured during that day),

and where columns represent the successive values of an item's property

(ex: the temperatures measured over the past year).

Sometimes, to make the representation easier to understand,

some cells of the grid are used to represent a description or summary of their parent row/column,

instead of actual data.

This happens more frequently for

the cells found on the first row and/or column (called headers)

or the cells found on the last row and/or column (called footers).

This kind of tabular data representation is usually known as tables.

Tables layout can be abused to render other grid-like representations like calendars or timelines,

though authors should prefer other layout modes

when the information being represented does not make sense as a data table.

The rendering of tables in HTML has been defined for a long time in the HTML specification.

However, its interactions with features defined in CSS remained for a long time undefined.

The goal of this specification is to define

the expected behavior of user agents supporting both HTML tables and CSS.

Please be aware that some behaviors defined in this document

will not be the most logical or useful way of solving the problem they aim to solve,

but such behaviors are often the result of compatibility requirements and not a deliberate choice

of the editors of this specification.

Authors wishing to use more complex layouts

are encouraged to rely on more modern CSS modules such as CSS Grid.

<wpt title="

The following tests are crash tests

that relate to general usage

of the features described in this specification

but are not tied to any particular normative statement.">

colspan-zero-crash.html

crashtests/caption-repaint-crash.html

crashtests/caption-with-multicol-table-cell.html

crashtests/cell-contents-with-negative-outer-size.html

crashtests/col_span_dynamic_crash.html

crashtests/dialog-table-crash.html

crashtests/dynamic-recompute-baseline.html

crashtests/dynamic_col_width_crash.html

crashtests/dynamic_table_layout_crash.html

crashtests/empty-tbody-after-tall-section-crash.html

crashtests/empty_cells_crash.html

crashtests/empty_table_with_cols.html

crashtests/expression_width_crash.html

crashtests/inline-splitting-crash.html

crashtests/large-border-crash.html

crashtests/large-col-widths.html

crashtests/legacy_ng_mix_crash.html

crashtests/move-oof-inside-section-row-with-borders.html

crashtests/negative-section-distribution.html

crashtests/negative_caption_margin.html

crashtests/orthogonal-cell-borders.html

crashtests/orthogonal-cell-crash.html

crashtests/table-column-display-change-chrome-crash.html

crashtests/textarea-intrinsic-size-crash.html

crashtests/atomic-item-crash.html

crashtests/remove-table-column-group.html

crashtests/transition-table-row-group-crash.html

crashtests/uninitialized_read_crash.html

table-caption-after-crash.html

crashtests/vertical_percentage_crash.html

tfoot-crash-print.html

th-text-align.html

toggle-row-display-property-001.html

table-collapsed-row-or-column-crash.html

</wpt>

<wpt title="Tests generally related to table layout">

absolute-tables-001.html

absolute-tables-006.html

anonymous-table-cell-margin-collapsing.html

chrome-rowspan-bug.html

col_removal.html

colspan-001.html

colspan-002.html

colspan-003.html

colspan-004.html

dynamic-rowspan-change.html

html-display-table.html

inheritance.html

multicol-table-collapsed-border-crash.html

multicol-table-crash.html

remove-caption-from-anon-table.html

remove-colgroup-from-anon-table.html

row-group-order.html

table-position-sticky-computed.html

table-cell-child-overflow-measure.html

table-cell-inline-size-box-sizing-quirks.html

table-cell-scroll-height.html

table-cell-writing-mode-computed.html

zero-rowspan-001.html

zero-rowspan-002.html

subpixel-table-cell-height-001.html

subpixel-table-width-001.html

</wpt>

<h3 id="values">Value Definitions</h3>

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

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

Value types not defined in this specification are defined in CSS Values &amp; Units [[!CSS-VALUES-3]].

Combination with other CSS modules may expand the definitions of these value types.

In addition to the property-specific values listed in their definitions,

all properties defined in this specification

also accept the <a>CSS-wide keywords</a> as their property value.

For readability they have not been repeated explicitly.

<!--

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

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

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

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

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

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

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

-->

<h2 id="content-model">Content Model</h2>

<!--——————————————————————————————————————————————————————————————————————————-->

<h3 id="table-structure">Table Structure</h3>

The CSS table model is based on the HTML4 table model,

in which the structure of a table closely parallels the visual layout of the table.

In this model, a table consists of an optional caption and any number of rows of cells.

In addition, adjacent rows and columns may be grouped structurally and

this grouping can be reflected in presentation (e.g., a border may be drawn around a group of rows).

The table model is said to be "row primary" since

authors specify rows, not columns, explicitly in the document language.

Columns are derived once all the rows have been specified:

the first cell of the first row belongs to the first column

and as many other columns as spanning requires (and it creates them if needed),

and the following cells of that row each belong to the next available column

and as many other columns as spanning requires (creating those if needed);

the cells of the following rows each belong to the next available column for that row (taking rowspan into account)

and as many other columns as spanning requires (creating those if needed).

<span class="hint">(see [[#dimensioning-the-row-column-grid]])</span>.

To summarize, an instance of the table model consists of:

<ul class="compact">

<li>Its <a href="#table-root-element">table-root</a> containing:

<ul>

<li>Zero, one or more <a href="#table-row">table rows</a>, optionally in <a href="#table-row-group">row groups</a>,

<ul><li>Each of them containing one or more <a href="#table-cell">table cells</a></li></ul>

<li>Optionally: one or more <a href="#table-column">table columns</a>,

optionally in <a href="#table-column-group">column groups</a>

<li>Optionally: one or more <a href="#table-caption">table caption</a>.

</ul>

</ul>

<style>

ul.compact { margin-top: -1em !important; list-style-type: disc; }

ul.compact li { margin-top: 0 !important; margin-bottom: 0 !important; list-style-type: disc; }

</style>

<figure>

<img alt="[see-caption-below]" src="images/table-structure.png" width=493>

<figcaption>Two representations of the structure of a table (tree vs layout)</figcaption>

</figure>

The CSS model does not require that the document language include elements that correspond to each of these components.

For document languages (such as XML applications) that do not have pre-defined table elements,

authors must map document language elements to table elements.

This is done with the 'display' property.

The following 'display' values assign table formatting rules to an arbitrary element:

<dl id="display-types">

<dt><dfn>table</dfn> (equivalent to HTML: &lt;table&gt;)

<dd>Specifies that an element defines a table

that is <a>block-level</a> when placed in <a>flow layout</a>.

<dt><dfn>inline-table</dfn> (equivalent to HTML: &lt;table&gt;)

<dd>Specifies that an element defines a table

that is <a>inline-level</a> when placed in <a>flow layout</a>.

<dt><dfn>table-row</dfn> (equivalent to HTML: &lt;tr&gt;)

<dd>Specifies that an element is a row of cells.

<dt><dfn>table-row-group</dfn> (equivalent to HTML: &lt;tbody&gt;)

<dd>Specifies that an element groups some amount of rows.

Unless explicitly mentioned otherwise, mentions of [=table-row-groups=] in this spec also encompass the specialized [=table-header-groups=] and [=table-footer-groups=].

<dt><dfn>table-header-group</dfn> (equivalent to HTML: &lt;thead&gt;)

<dd>Like [=table-row-group=] but, for layout purposes,

the first such row group is always displayed before all other rows and row groups.

<div class="advisement">

If a table owns multiple <code>display: table-header-group</code> boxes,

only the first is treated as a header;

the others are treated as if they had <code>display: table-row-group</code>.

</div>

<dt><dfn>table-footer-group</dfn> (equivalent to HTML: &lt;tfoot&gt;)

<dd>Like [=table-row-group=] but, for layout purposes,

the first such row group is always displayed after all other rows and row groups.

<div class="advisement">

If a table owns multiple <code>display: table-footer-group</code> boxes,

only the first is treated as a footer;

the others are treated as if they had <code>display: table-row-group</code>.

</div>

<dt><dfn>table-column</dfn> (equivalent to HTML: &lt;col&gt;)

<dd>Specifies that an element describes a column of cells.

<dt><dfn>table-column-group</dfn> (equivalent to HTML: &lt;colgroup&gt;)

<dd>Specifies that an element groups one or more columns.

<dt><dfn>table-cell</dfn> (equivalent to HTML: &lt;td&gt; or &lt;th&gt;)

<dd>Specifies that an element represents a table cell.

<dt><dfn>table-caption</dfn> (equivalent to HTML: &lt;caption&gt;)

<dd>Specifies a caption for the table.

Table captions are positioned between the table margins and its borders.

<wpt>

caption-cyclic-percentage.html

caption-writing-mode-001.html

caption-writing-mode-002.html

</wpt>

</dl>

Note: [=Replaced elements=] with a 'display' value of

''table-row'',

''table-row-group'',

''table-header-group'',

''table-footer-group'',

''table-column'',

''table-column-group'',

''table-cell'',

and ''table-caption''

are treated as [=inline-level boxes=],

as per [[css-display-3#layout-specific-display]];

[=replaced elements=] with a 'display' value of ''table'' or ''inline-table''

behave according to their [=outer display type=],

as per [[css-display-3#outer-role]].

<strong>This is a breaking change from CSS 2.1 but matches implementations.</strong>

<wpt>

table-model-fixup-2.html

</wpt>

<h4 id="terminology">Terminology</h4>

In addition to the table structure display types,

the following wording is also being used in this spec:

<dl export>

<dt><dfn lt="table wrapper box | table-wrapper box" local-lt="table-wrapper">table wrapper box</dfn>

<dd>

A block container box <a href="#fixup-algorithm">generated around table grid boxes</a>

to account for any space occupied by each <a>table-caption</a> it owns.

<dt><dfn lt="table grid box | table-grid box" local-lt="table-grid">table grid box</dfn>

<dd>

A block-level box containing the table-internal boxes, excluding its captions.

<dt><dfn id="table-root-element">table-root</dfn> element

<dd>

An element whose <a>inner display type</a> is ''display/table''.

<dt><dfn id="table-non-root-element">table-non-root</dfn> box or element

<dd>

A <a>proper table child</a>, or a <a>table-cell</a> box.

<dt><dfn id="table-track">table-track</dfn> box or element

<dd>

A

<a>table-row</a>, or

<a>table-column</a> box.

<dt><dfn id="table-track-group-element">table-track-group</dfn> box or element

<dd>

A

<a>table-row-group</a>, or

<a>table-column-group</a> box.

<dt><dfn id="proper-table-child-element">proper table child</dfn> box or element

<dd>

A

<a>table-track-group</a>,

<a>table-track</a>, or

<a>table-caption</a> box.

<dt><dfn id="proper-table-row-parent-element">proper table-row parent</dfn> box or element

<dd>

A <a>table-root</a> or a <a>table-row-group</a> box.

<dt><dfn id="table-internal-element">table-internal</dfn> box or element

<dd>

A <a>table-cell</a>, <a>table-track</a> or <a>table-track-group</a> box.

<dt><dfn id="tabular-container">tabular container</dfn>

<dd>

A <a>table-row</a> or <a>proper table-row parent</a> box.

<dt><dfn noexport id="consecutive-boxes">consecutive</dfn> boxes

<dd>

Two sibling boxes are consecutive

if they have no intervening siblings

other than, optionally, an anonymous inline containing only white spaces.

A sequence of sibling boxes is consecutive

if each box in the sequence is consecutive to the one before it in the sequence.

<wpt>

whitespace-001.html

</wpt>

<dt><dfn id="table-grid">table grid</dfn>

<dd>

A matrix

containing as many <dfn id="row">rows</dfn> and <dfn id="column">columns</dfn>

as needed to describe the position of all the <a>table-rows</a> and <a>table-cells</a> of a <a>table-root</a>,

as determined by the <a href="#dimensioning-the-row-column-grid">grid-dimensioning algorithm</a>.

Each row of the grid might correspond to a <a>table-row</a>, and each column to a <a>table-column</a>.

<dt><dfn noexport id="slot">slot</dfn> of the table grid

<dd>

A <a>slot</a> <code>(r,c)</code> is an available space created

by the intersection of a row <code>r</code> and a column <code>c</code> in the <a>table grid</a>.

Each slot of the table grid is covered by at least one <a>table-cell</a> (<a href="#missing-cells-fixup">some of them anonymous</a>), and at most two.

Each table-cell of a table-root covers at least one slot.

Table-cells which cover more than one slot do so densely,

meaning the set of slots they cover can always be described as a set of four strictly-positive integers <code>(rowStart, colStart, rowSpan, colSpan)</code>

such that a slot <code>(r,c)</code> is covered by the table-cell

if and only if <code>r</code> lies in the interval between <code>rowStart</code> (included) and <code>rowStart+rowSpan</code> (excluded),

and <code>c</code> lies in the interval between <code>colStart</code> (included) and <code>colStart+colSpan</code> (excluded);

Such table-cell is said to <dfn>originate</dfn> from row <code>rowStart</code> and column <code>colStart</code>.

Also:

<ul><li>A table-cell is said to originate a table-row <i>(resp. table-column)</i> if it originates its corresponding row <i>(resp. column)</i>

<li>A table-cell is said to originate a table-row-group <i>(resp. table-column-group)</i> if the group contains the cell's originating row <i>(resp. column)</i>

</ul>

Such table-cell is said to <dfn>span</dfn> all rows <code>r</code> and columns <code>c</code> matching the above condition.

Also:

<ul><li>A table-cell is said to span a table-row <i>(resp. table-column)</i> if it spans its corresponding row <i>(resp. column)</i>

<li>A table-row <i>(resp. table-column)</i> corresponding to a row <i>(resp. column)</i> is said to span this row <i>(resp. column)</i>

<li>A table-row <i>(resp. table-column)</i> is said to span all columns of the grid <i>(resp. row)</i>

<li>A table-row-group <i>(resp. table-column)</i> containing a row <i>(resp. column)</i> is said to span the row <i>(resp. column)</i>

<li>A table-row-group <i>(resp. table-column)</i> is said to span all columns of the grid <i>(resp. row)</i>

</ul>

</dl>

<!--

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

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

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

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

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

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

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

-->

<h3 id="fixup">Fixup</h3>

Document languages other than HTML may not contain all the elements in the CSS 2.1 table model.

In these cases, the "missing" elements must be assumed in order for the table model to work.

Any <a>table-internal</a> element will automatically generate necessary anonymous table objects around itself, if necessary.

Any descendant of a <a>table-root</a> that is not table-internal

must have a set of ancestors in the table consisting of

at least three nested objects corresponding to

a <a>table</a>/<a>inline-table</a>,

a <a>table-row</a>, and

a <a>table-cell</a>.

Missing boxes cause the generation of <a href="#fixup-boxes">anonymous boxes</a> according to the following rules:

<!--——————————————————————————————————————————————————————————————————————————-->

<h4 id="fixup-algorithm">Fixup Algorithm</h4>

For the purposes of these rules, <a>out-of-flow</a> elements are represented as inline elements of zero width and height.

Their containing blocks are chosen accordingly.

The following steps are performed in three stages:

<ol>

<li><b>Remove irrelevant boxes:</b><br/>

The following boxes are discarded as if they were <code>display:none</code>:

<ol>

<li>Children of a <a>table-column</a>.

<li>Children of a <a>table-column-group</a> which are not a <a>table-column</a>.

<li>Anonymous inline boxes which contain only white space and

are between two immediate siblings each of which is a <a>table-non-root</a> box.

<li>Anonymous inline boxes which meet all of the following criteria:

<ul>

<li>they contain only white space

<li>they are the first and/or last child of a <a>tabular container</a>

<li>whose immediate sibling, if any, is a <a>table-non-root</a> box

</ul>

</ol>

</li>

<li><b>Generate missing child wrappers:</b>

<ol>

<li>An anonymous <a>table-row</a> box must be generated

around each sequence of consecutive children of a <a>table-root</a> box

which are not <a>proper table child</a> boxes.

<a class="hint" href="https://jsfiddle.net/hj2w7wwa/2/">!!Testcase</a>

<li>An anonymous <a>table-row</a> box must be generated

around each sequence of consecutive children of a <a>table-row-group</a> box

which are not <a>table-row</a> boxes.

<a class="hint" href="https://jsfiddle.net/hj2w7wwa/3/">!Testcase</a>

<li>An anonymous <a>table-cell</a> box must be generated

around each sequence of consecutive children of a <a>table-row</a> box

which are not <a>table-cell</a> boxes.

<a class="hint" href="https://jsfiddle.net/hj2w7wwa/4/">!Testcase</a>

</ol>

</li>

<li><b>Generate missing parents:</b>

<ol>

<li>An anonymous <a>table-row</a> box must be generated

around each sequence of consecutive <a>table-cell</a> boxes

whose parent is not a <a>table-row</a>.

<a class="hint" href="https://jsfiddle.net/hj2w7wwa/5/">Testcase</a>

<li>An anonymous <a>table</a> or <a>inline-table</a> box must be generated

around each sequence of consecutive <a>proper table child</a> boxes

which are misparented.

If the box's parent is an inline, run-in, or ruby box (or any box that would perform inlinification of its children),

then an <a>inline-table</a> box must be generated;

otherwise it must be a <a>table</a> box.

<ul>

<li>A <a>table-row</a> is misparented

if its parent is neither a <a>table-row-group</a> nor a <a>table-root</a> box.

<li>A <a>table-column</a> box is misparented

if its parent is neither a <a>table-column-group</a> box nor a <a>table-root</a> box.

<li>A <a>table-row-group</a>, <a>table-column-group</a>, or <a>table-caption</a> box is misparented

if its parent is not a <a>table-root</a> box.

</ul>

<a class="hint" href="https://jsfiddle.net/hj2w7wwa/7/">Testcase</a>

<a class="hint" href="https://jsfiddle.net/hj2w7wwa/8/">Testcase</a>

<a class="hint" href="https://jsfiddle.net/hj2w7wwa/9/">!Testcase</a>

<li>An anonymous <a>table-wrapper</a> box must be generated around each <a>table-root</a>.

Its display type is <code>inline-block</code> for <a>inline-table</a> boxes and block for <a>table</a> boxes.

The table wrapper box establishes a block formatting context.

The table-root box (not the table-wrapper box) is used when doing baseline vertical alignment for an <a>inline-table</a>.

The width of the table-wrapper box is the border-edge width of the table grid box inside it.

Percentages which would depend on the 'width' and 'height' on the table-wrapper box's size are relative to the table-wrapper box's containing block instead, not the table-wrapper box itself.

</ol>

</li>

</ol>

<div class="note">

Please note that some layout modes such as flexbox and grid <a href="http://www.w3.org/TR/css-display-3/#blockify">override the display type</a> of their children.

These transformations happen before the table fixup.

</div>

<div class="note">

Please note that the 'float' and 'position' properties sometimes <a href="http://www.w3.org/TR/CSS22/visuren.html#dis-pos-flo">affect the computed value</a> of 'display'.

When those properties are used on what should have been table internal boxes, they switch to <code>block</code> instead.

This transformation happens before the table fixup.

</div>

<div class="note">

We have modified the text of this section from CSS 2.2 to make it easier to read.

If you find any mistakes due to these changes please file an issue

</div>

<wpt>

anonymous-table-ws-001.html

fixup-dynamic-anonymous-inline-table-001.html

fixup-dynamic-anonymous-inline-table-002.html

fixup-dynamic-anonymous-inline-table-003.html

fixup-dynamic-anonymous-table-001.html

iframe-display-table-content-insertion.html

insert-after-col.html

insert-after-colgroup.html

table-model-fixup.html

table-row-group-nested-anonymous-001.html

</wpt>

<!--——————————————————————————————————————————————————————————————————————————-->

<h4 id="fixup-boxes">Characteristics of fixup boxes</h4>

Beside their display type, the anonymous boxes created for fixup purposes

do not receive any specific or default styling,

except where otherwise mentioned by this specification.

<div class="note">

This means in particular that

their computed background is “transparent”,

their computed padding is “0px”,

their computed border-style is “none”.

It is also worth reminding that an <a>anonymous box</a> inherits property values through the box tree.

</div>

<!--——————————————————————————————————————————————————————————————————————————-->

<h4 id="fixup-examples">Examples</h4>

<div class="example">

<xmp class="lang-markup">

<div class="row">

<div class="cell">George</div>

<div class="cell">4287</div>

<div class="cell">1998</div>

</div>

</xmp>

Here is the associated styles:

<pre class="lang-css">

.row { display: table-row }

.cell { display: table-cell }

</pre>

After fixup, this will produce layout boxes as though this was the initial HTML:

<xmp class="lang-markup">

<table>

<tr>

<td>George</td>

<td>4287</td>

<td>1998</td>

</tr>

</table>

</xmp>

</div>

<div class="example">

In this example, three <a>table-cell</a> anonymous boxes are assumed to contain the text in the rows. The text inside

of the divs with a <code>display: table-row</code> are encapsulated in anonymous inline boxes, as explained in

<a href="https://www.w3.org/TR/CSS21/visuren.html#anonymous" target="_blank">visual formatting model</a>:

<xmp class="lang-markup">

<div class="inline-table">

<div class="row">This is the top row.</div>

<div class="row">This is the middle row.</div>

<div class="row">This is the bottom row.</div>

</div>

</xmp>

<pre class="lang-css">

.inline-table { display: inline-table; }

.row { display: table-row; }

</pre>

This will produce layout boxes as though this was the initial HTML:

<xmp class="lang-markup">

<table>

<tr>

<td>This is the top row.</td>

</tr>

<tr>

<td>This is the middle row.</td>

</tr>

<tr>

<td>This is the bottom row.</td>

</tr>

</table>

</xmp>

</div>

<!--

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

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

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

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

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

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

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

-->

<h2 id="layout">Layout</h2>

<!--——————————————————————————————————————————————————————————————————————————-->

<h3 id="layout-principles">Core layout principles</h3>

Unlike other block-level boxes, tables do not fill their containing block by default.

When their 'width' computes to <code>auto</code>, they behave as if they had <code>fit-content</code> specified instead.

This is different from most block-level boxes, which behave as if they had <code>stretch</code> instead.

The <dfn id="min-content-width-of-a-table" export>min-content width of a table</dfn> is

the width required to fit all of its columns min-content widths and its [=undistributable spaces=].

The <dfn id="max-content-width-of-a-table" export>max-content width of a table</dfn> is

the width required to fit all of its columns max-content widths and its [=undistributable spaces=].

If the width assigned to a table is larger than its <a href="#min-content-width-of-a-table">min-content width</a>,

the <a href="#width-distribution">Available Width Distribution</a> algorithm

will adjust column widths in consequence.

This section overrides the general-purpose rules that apply to calculating widths described in other specifications.

In particular, if the margins of a table are set to <code>0</code> and the width to <code>auto</code>,

the table will not automatically size to fill its containing block.

However, once the used value of <code>width</code> for the table is found (using the algorithms given below)

then the other parts of those rules do apply.

Therefore, a table can be centered using left and right <code>auto</code> margins, for instance.

<!--——————————————————————————————————————————————————————————————————————————-->

<h3 id="table-layout-algorithm">Table layout algorithm</h3>

To layout a table, user agents must apply the following actions:

<ol>

<li><b>Determine the number of rows/columns the table requires.</b><br/>

This is done by executing the steps described in [[#dimensioning-the-row-column-grid]].

<li><b>&lbrack;A&rbrack; If the row/column grid has at least one <a>slot</a>:</b>

<ol>

<li><b>Ensure each cell <a>slot</a> is occupied by at least one cell.</b><br/>

This is done by executing the steps described in [[#missing-cells-fixup]].

<li><b>Compute the minimum width of each column.</b><br/>

This is done by executing the steps described in [[#content-measure]].

<li><b>Compute the width of the table.</b><br/>

This is done by executing the steps described in [[#computing-the-table-width]].

<li><b>Distribute the width of the table among columns.</b><br/>

This is done by executing the steps described in [[#width-distribution-algorithm]].

<li><b>Compute the height of the table.</b><br/>

This is done by executing the steps described in [[#computing-the-table-height]].

<li><b>Distribute the height of the table among rows.</b><br/>

This is done by executing the steps described in [[#height-distribution-algorithm]].

</ol>

<b>&lbrack;B&rbrack; Else, an <dfn id="empty-table">empty table</dfn> is laid out:</b>

<ol>

<li><b>Compute the width of the table.</b><br/>

This is done by returning the largest value of <a href="#capmin">CAPMIN</a>

and the computed width of the table grid box (including borders and paddings)

if it is definite (use zero otherwise).

<li><b>Compute the height of the table.</b><br/>

This is done by returning the sum of all table-caption heights

(their width being set to the table width,

with margins taken into consideration appropriately)

and the computed height of the table grid box (including borders and paddings)

if it is definite (use zero otherwise).

</ol>

<li><b>Assign to each table-caption and table-cell their position and size.</b><br/>

This is done by running the steps of [[#bounding-box-assignment]].

</ol>

<figure>

<p class="note">

The following schema describes the algorithm in a different way,

to make it easier to understand.

</p>

<img alt="[see-caption-below]" src="images/CSS-Tables-Layout-Merged.svg" width=800 style="width: 100%">

<figcaption>Overview of the table layout algorithm. Not normative.</figcaption>

</figure>

<wpt>

html5-table-formatting-1.html

</wpt>

<!--——————————————————————————————————————————————————————————————————————————-->

<h3 id="dimensioning-the-row-column-grid">Dimensioning the row/column grid</h3>

Like mentioned in the <a href="#table-structure">Table structure</a> section,

how many rows and columns a table has

can be determined from the table structure.

Both dimensioning the row/column <a>grid</a> and assigning table-cells their <nobr><a>slot</a>(s)</nobr> in that grid

do require running the HTML Algorithms for tables.

<h4 id="dimensioning-the-row-column-grid--step1">HTML Algorithm</h4>

<p class="note">

CSS Boxes that do not originate from an HTML table element equivalent to their display type

need to be converted to their HTML equivalent before we can apply this algorithm, see below.

There is no way to specify the <a>span</a> of a cell in css only in this level of the spec,

the use of an HTML td element is required to do so.

Apply the <a href="https://www.w3.org/TR/html5/tabular-data.html#forming-a-table">HTML5 Table Formatting algorithm</a>,

where boxes act like <a href="#display-types">the HTML element equivalent to their display type</a>,

and use the attributes of their originating element if and only if it is an HTML element of the same type

(otherwise, they act like if they didn't have any attribute).

<div class="example">

<xmp class="lang-markup">

<ul class="table">

<li><b>One</b><i>1</i></li>

<li><b>Two</b><i>2</i></li>

<li><b>Three</b><i>3</i></li>

</ul>

<style>

ul.table { display: table; }

ul.table > li { display: table-row; }

ul.table > li > * { display: table-cell; }

</style>

</xmp>

produces the same row/column grid as

<xmp class="lang-markup">

<table><tbody>

<tr>

<td></td>

<td></td>

</tr>

<tr>

<td></td>

<td></td>

</tr>

<tr>

<td></td>

<td></td>

</tr>

</tbody></table>

</xmp>

</div>

<div class="example">

<pre class="lang-markup" style="margin-bottom:0;padding-bottom:0;">

&lt;!-- built using dom api, as this would be fixed by the html parser --&gt;

</pre>

<xmp class="lang-markup" style="margin-top:0;padding-top:0;">

<grid style="display: table">

<row style="display: table-row">

<th rowspan="2">1</th>

<colgroup style="display: table-cell" span="2" colspan="2">2</colgroup>

</row>

<tr>

<td>A</td>

<td>B</td>

<td>C</td>

</tr>

</grid>

</xmp>

produces the same row/column grid as

<xmp class="lang-markup">

<table>

<tr>

<th rowspan="2">1</th>

<td>2</td>

</tr>

<tr>

<td>A</td>

<td>B</td>

<td>C</td>

</tr>

</table>

</xmp>

Note how the second cell of the first row doesn't have ```colspan=2``` applied, because its originating element is not an HTML TD element.

<a class="hint" href="https://jsfiddle.net/eqrwaLyc/">Testcase</a>.

<a class="hint" href="https://jsfiddle.net/eqrwaLyc/1/">!!Testcase</a>.

<a class="hint" href="https://jsfiddle.net/sckxeLmh/2/">!Test case</a>.

<a class="hint" href="https://jsfiddle.net/sckxeLmh/4/">!!Test case</a>.

<a class="hint" href="https://jsfiddle.net/sckxeLmh/5/">!!Test case</a>.

</div>

<wpt>

html5-table-formatting-fixed-layout-1.html

table_grid_size_col_colspan.html

</wpt>

<h4 id="dimensioning-the-row-column-grid--step2">Track merging</h4>

<p class="note">

The HTML Table Formatting algorithm sometimes generates more tracks than necessary to layout the table properly.

Those tracks have historically been ignored by user agents,

so the next step just gets rid of them entirely to avoid dealing with them as exceptions later in the spec.

We have tried to maintain the functionality with this change, but if you happen to find any issues

due to this change please file an issue.

Modify iteratively the obtained grid by merging consecutive tracks as follows:

As long as there exists an <a>eligible track</a> in the obtained row/column grid such that

there is no table-column/table-row box defining the said track explicitly, and

both the said track and the previous one are spanned by the exact same set of cells,

those two tracks must be merged into one single track for the purpose of computing the layout of the table.

Reduce the <a>span</a> of the cells that spanned the deleted track by one to compensate,

and shift similarly the tracks from which cells <a>originate</a> when needed.

<span class="hint">(see <a href="#spanning-ghost-rows">spanning-ghost-rows test cases</a>)</span>

For tables <a>in auto mode</a>, every track is an <dfn>eligible track</dfn> for the purpose of the track-merging algorithm.

For tables <a>in fixed mode</a>, only rows are eligible to be merged that way; which means that every column is preserved.

Finally, assign to the <a>table-root</a> grid its correct number of rows and columns (from its mapped element),

and to each <a>table-cell</a> its accurate <a href="#slot">rowStart/colStart/rowSpan/colSpan</a> (from its mapped element).

<wpt>

column-track-merging.html

</wpt>

<!--——————————————————————————————————————————————————————————————————————————-->

<h3 id="missing-cells-fixup">Missing cells fixup</h3>

<p class=note>

The following section clarifies and extends the CSS 2.1 statement saying that

missing cells are rendered as if an anonymous table-cell box occupied their position in the grid

(a "missing cell" is a slot in the row/column grid that is not covered yet by any table-cell box).

Once the amount of columns in a table is known, any table-row box must be modified such that

it owns enough cells to fill all the columns of the table, when taking <a>spans</a> into account.

New table-cell <a href="#fixup-boxes">anonymous boxes</a> must be appended to its rows content until this condition is met.

<wpt>

col-definite-max-size-001.html

col-definite-min-size-001.html

col-definite-size-001.html

html5-table-formatting-2.html

html5-table-formatting-3.html

</wpt>

<!--——————————————————————————————————————————————————————————————————————————-->

<h3 id="layout-modes">Table layout modes</h3>

This section covers the flags which modify the way tables are being laid out.

There are three major flags for table layout: 'table-layout', 'border-collapse', and 'caption-side'.

The 'border-collapse' flag has an optional 'border-spacing' parameter.

<!--——————————————————————————————————————————————————————————————————————————-->

<h4 id="table-layout-property">The Table-Layout property</h4>

<pre class='propdef'>

Name: table-layout

Value: auto | fixed

Initial: auto

Applies to: <a>table grid boxes</a>

Inherited: no

Computed value: specified keyword

Animation type: discrete

</pre>

<wpt>

parsing/table-layout-computed.html

parsing/table-layout-invalid.html

parsing/table-layout-valid.html

</wpt>

A table-root is said to be laid out <dfn>in fixed mode</dfn>

whenever the computed value of the 'table-layout' property is equal to <code>fixed</code>,

and the specified width of the table root is either

a <code>&lt;length-percentage&gt;</code>,

<code>min-content</code> or

<code>fit-content</code>.

When the specified width is not one of those values,

or if the computed value of the 'table-layout' property is <code>auto</code>,

then the table-root is said to be laid out <dfn>in auto mode</dfn>.

When a table-root is laid out <a>in fixed mode</a>,

the content of its table-cells is ignored for the purpose of width computation,

the aggregation algorithm for column sizing considers only table-cells belonging to the first row track,

such that layout only depends on the values explicitly specified for the table-columns or cells of the first row of the table;

columns with indefinite widths are attributed their fair share of the remaining space

after the columns with a definite width have been considered, or 0px if there is no remaining space

(see [[#computing-column-measures]]).

<!--——————————————————————————————————————————————————————————————————————————-->

<h4 id="border-collapse-property">The Border-Collapse property</h4>

<pre class='propdef'>

Name: border-collapse

Value: separate | collapse

Initial: separate

Applies To: <a>table grid boxes</a>

Inherited: yes

Computed value: specified keyword

Animation type: discrete

</pre>

When the 'border-collapse' property has <code>collapse</code> as its value,

the borders of adjacent cells are merged together such that each cell draws only half of the shared border.

As a result, some other properties like 'border-spacing' will not applied in this case (see [[#collapsed-style-overrides]]),

(see [[#border-collapsing]]).

A <a>table-root</a> is said to be laid out <dfn>in collapsed-borders mode</dfn> in this case.

Otherwise, the <a>table-root</a> is said to be laid out <dfn>in separated-borders mode</dfn>.

<wpt>

background-clip-001.html

box-shadow-001.html

collapsed-border-color-change-with-compositing.html

collapsed-border-remove-row-group.html

collapsed-scroll-overflow.html

parsing/border-collapse-computed.html

parsing/border-collapse-invalid.html

parsing/border-collapse-valid.html

</wpt>

<!--——————————————————————————————————————————————————————————————————————————-->

<h5 id="border-spacing-property">The Border-Spacing property</h5>

<pre class='propdef'>

Name: border-spacing

Value: <<length [0,∞]>>{1,2}

Initial: 0px 0px

Inherited: yes

Applies To: <a>table grid boxes</a> when 'border-collapse' is ''border-collapse/separate''

Computed Value: two absolute lengths

Animation type: by computed value

</pre>

The lengths specify the distance that separates adjoining cell borders <a>in separated-borders mode</a>,

and must be non-negative.

If one length is specified, it gives both the horizontal and vertical spacing.

If two are specified, the first gives the horizontal spacing and the second the vertical spacing.

See [[#computing-undistributable-space]] for details on how this affects the table layout.

<wpt>

animations/border-spacing-interpolation.html

parsing/border-spacing-computed.html

parsing/border-spacing-invalid.html