CSS Table Module Level 3

1. Introduction

This section is not normative

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.

1.1. Value Definitions

This specification follows the CSS property definition conventions from [CSS2] using the value definition syntax from [CSS-VALUES-3]. Value types not defined in this specification are defined in CSS Values & Units [CSS-VALUES-3]. Combination with other CSS modules may expand the definitions of these value types.

In addition to the property-specific values listed in their definitions, all properties defined in this specification also accept the CSS-wide keywords as their property value. For readability they have not been repeated explicitly.

2. Content Model

2.1. Table Structure

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). (see § 3.3 Dimensioning the row/column grid).

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

• Its table-root containing:
  • Zero, one or more table rows, optionally in row groups,
    • Each of them containing one or more table cells
  • Optionally: one or more table columns, optionally in column groups
  • Optionally: one or more table caption.

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:

table (equivalent to HTML: <table>)

Specifies that an element defines a table that is block-level when placed in flow layout.

inline-table (equivalent to HTML: <table>)

Specifies that an element defines a table that is inline-level when placed in flow layout.

table-row (equivalent to HTML: <tr>)

Specifies that an element is a row of cells.

table-row-group (equivalent to HTML: <tbody>)

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.

table-header-group (equivalent to HTML: <thead>)

Like table-row-group but, for layout purposes, the first such row group is always displayed before all other rows and row groups.

If a table owns multiple display: table-header-group boxes, only the first is treated as a header; the others are treated as if they had display: table-row-group.

table-footer-group (equivalent to HTML: <tfoot>)

Like table-row-group but, for layout purposes, the fist such row group is always displayed after all other rows and row groups.

If a table owns multiple display: table-footer-group boxes, only the first is treated as a footer; the others are treated as if they had display: table-row-group.

table-column (equivalent to HTML: <col>)

Specifies that an element describes a column of cells.

table-column-group (equivalent to HTML: <colgroup>)

Specifies that an element groups one or more columns.

table-cell (equivalent to HTML: <td> or <th>)

Specifies that an element represents a table cell.

table-caption (equivalent to HTML: <caption>)

Specifies a caption for the table. Table captions are positioned between the table margins and its borders.

Tests

• caption-cyclic-percentage.html (live test) (source)
• caption-writing-mode-001.html (live test) (source)
• caption-writing-mode-002.html (live test) (source)

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 § 2.4 Layout-Internal Display Types: the table-* and ruby-* keywords; replaced elements with a display value of table or inline-table behave according to their outer display type, as per CSS Display 3 § 2.1 Outer Display Roles for Flow Layout: the block, inline, and run-in keywords. This is a breaking change from CSS 2.1 but matches implementations.

2.1.1. Terminology

In addition to the table structure display types, the following wording is also being used in this spec:

table wrapper box

A block container box generated around table grid boxes to account for any space occupied by each table-caption it owns.

table grid box

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

table-root element

An element whose inner display type is table.

table-non-root box or element

A proper table child, or a table-cell box.

table-track box or element

A table-row, or table-column box.

table-track-group box or element

A table-row-group, or table-column-group box.

proper table child box or element

A table-track-group, table-track, or table-caption box.

proper table-row parent box or element

A table-root or a table-row-group box.

table-internal box or element

A table-cell, table-track or table-track-group box.

tabular container

A table-row or proper table-row parent box.

consecutive boxes

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.

Tests

• whitespace-001.html (live test) (source)

table grid

A matrix containing as many rows and columns as needed to describe the position of all the table-rows and table-cells of a table-root, as determined by the grid-dimensioning algorithm.

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

slot of the table grid

A slot (r,c) is an available space created by the intersection of a row r and a column c in the table grid.

Each slot of the table grid is covered by at least one table-cell (some of them anonymous), 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 (rowStart, colStart, rowSpan, colSpan) such that a slot (r,c) is covered by the table-cell if and only if r lies in the interval between rowStart (included) and rowStart+rowSpan (excluded), and c lies in the interval between colStart (included) and colStart+colSpan (excluded);

Such table-cell is said to originate from row rowStart and column colStart. Also:

• A table-cell is said to originate a table-row (resp. table-column) if it originates its corresponding row (resp. column)
• A table-cell is said to originate a table-row-group (resp. table-column-group) if the group contains the cell’s originating row (resp. column)

Such table-cell is said to span all rows r and columns c matching the above condition. Also:

• A table-cell is said to span a table-row (resp. table-column) if it spans its corresponding row (resp. column)
• A table-row (resp. table-column) corresponding to a row (resp. column) is said to span this row (resp. column)
• A table-row (resp. table-column) is said to span all columns of the grid (resp. row)
• A table-row-group (resp. table-column) containing a row (resp. column) is said to span the row (resp. column)
• A table-row-group (resp. table-column) is said to span all columns of the grid (resp. row)

2.2. Fixup

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 table-internal element will automatically generate necessary anonymous table objects around itself, if necessary. Any descendant of a table-root that is not table-internal must have a set of ancestors in the table consisting of at least three nested objects corresponding to a table/inline-table, a table-row, and a table-cell. Missing boxes cause the generation of anonymous boxes according to the following rules:

2.2.1. Fixup Algorithm

For the purposes of these rules, out-of-flow 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:

1. Remove irrelevant boxes:
   The following boxes are discarded as if they were display:none:
   1. Children of a table-column.
   2. Children of a table-column-group which are not a table-column.
   3. Anonymous inline boxes which contain only white space and are between two immediate siblings each of which is a table-non-root box.
   4. Anonymous inline boxes which meet all of the following criteria:
      • they contain only white space
      • they are the first and/or last child of a tabular container
      • whose immediate sibling, if any, is a table-non-root box
2. Generate missing child wrappers:
   1. An anonymous table-row box must be generated around each sequence of consecutive children of a table-root box which are not proper table child boxes. !!Testcase
   2. An anonymous table-row box must be generated around each sequence of consecutive children of a table-row-group box which are not table-row boxes. !Testcase
   3. An anonymous table-cell box must be generated around each sequence of consecutive children of a table-row box which are not table-cell boxes. !Testcase
3. Generate missing parents:
   1. An anonymous table-row box must be generated around each sequence of consecutive table-cell boxes whose parent is not a table-row. Testcase
   2. An anonymous table or inline-table box must be generated around each sequence of consecutive proper table child 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 inline-table box must be generated; otherwise it must be a table box.
      • A table-row is misparented if its parent is neither a table-row-group nor a table-root box.
      • A table-column box is misparented if its parent is neither a table-column-group box nor a table-root box.
      • A table-row-group, table-column-group, or table-caption box is misparented if its parent is not a table-root box.
      Testcase Testcase !Testcase
   3. An anonymous table-wrapper box must be generated around each table-root. Its display type is inline-block for inline-table boxes and block for table 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 inline-table. 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.

2.2.2. Characteristics of fixup boxes

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.

2.2.3. Examples

<div class="row">
  <div class="cell">George</div>
  <div class="cell">4287</div>
  <div class="cell">1998</div>
</div>

.row { display: table-row }
.cell { display: table-cell }

<table>
  <tr>
    <td>George</td>
    <td>4287</td>
    <td>1998</td>
  </tr>
</table>

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

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

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

3. Layout

3.1. Core layout principles

Unlike other block-level boxes, tables do not fill their containing block by default. When their width computes to auto, they behave as if they had fit-content specified instead. This is different from most block-level boxes, which behave as if they had stretch instead.

The min-content width of a table is the width required to fit all of its columns min-content widths and its undistributable spaces.

The max-content width of a table 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 min-content width, the Available Width Distribution 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 0 and the width to auto, the table will not automatically size to fill its containing block. However, once the used value of width 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 auto margins, for instance.

3.2. Table layout algorithm

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

1. Determine the number of rows/columns the table requires.
   This is done by executing the steps described in § 3.3 Dimensioning the row/column grid.
2. [A] If the row/column grid has at least one slot:
   1. Ensure each cell slot is occupied by at least one cell.
      This is done by executing the steps described in § 3.4 Missing cells fixup.
   2. Compute the minimum width of each column.
      This is done by executing the steps described in § 3.8 Computing table measures.
   3. Compute the width of the table.
      This is done by executing the steps described in § 3.9.1 Computing the table width.
   4. Distribute the width of the table among columns.
      This is done by executing the steps described in § 3.9.3 Distribution algorithm.
   5. Compute the height of the table.
      This is done by executing the steps described in § 3.10.1 Computing the table height.
   6. Distribute the height of the table among rows.
      This is done by executing the steps described in § 3.10.5 Distribution algorithm.

   [B] Else, an empty table is laid out:

   1. Compute the width of the table.
      This is done by returning the largest value of CAPMIN and the computed width of the table grid box (including borders and paddings) if it is definite (use zero otherwise).
   2. Compute the height of the table.
      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).
3. Assign to each table-caption and table-cell their position and size.
   This is done by running the steps of § 3.11 Positioning of cells, captions and other internal table boxes.

The following schema describes the algorithm in a different way, to make it easier to understand.

3.3. Dimensioning the row/column grid

Like mentioned in the Table structure section, how many rows and columns a table has can be determined from the table structure. Both dimensioning the row/column grid and assigning table-cells their slot(s) in that grid do require running the HTML Algorithms for tables.

3.3.1. HTML Algorithm

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 span 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 HTML5 Table Formatting algorithm, where boxes act like the HTML element equivalent to their display type, 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).

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

<table><tbody>
  <tr>
    <td></td>
    <td></td>
  </tr>
  <tr>
    <td></td>
    <td></td>
  </tr>
  <tr>
    <td></td>
    <td></td>
  </tr>
</tbody></table>

<!-- built using dom api, as this would be fixed by the html parser -->

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

<table>
  <tr>
    <th rowspan="2">1</th>
    <td>2</td>
  </tr>
  <tr>
    <td>A</td>
    <td>B</td>
    <td>C</td>
  </tr>
</table>

3.3.2. Track merging

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 eligible track 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 span of the cells that spanned the deleted track by one to compensate, and shift similarly the tracks from which cells originate when needed. (see spanning-ghost-rows test cases)

For tables in auto mode, every track is an eligible track for the purpose of the track-merging algorithm. For tables in fixed mode, only rows are eligible to be merged that way; which means that every column is preserved.

Finally, assign to the table-root grid its correct number of rows and columns (from its mapped element), and to each table-cell its accurate rowStart/colStart/rowSpan/colSpan (from its mapped element).

3.4. Missing cells fixup

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 spans into account. New table-cell anonymous boxes must be appended to its rows content until this condition is met.

3.5. Table layout modes

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.

3.5.1. The Table-Layout property

A table-root is said to be laid out in fixed mode whenever the computed value of the table-layout property is equal to fixed, and the specified width of the table root is either a <length-percentage>, min-content or fit-content. When the specified width is not one of those values, or if the computed value of the table-layout property is auto, then the table-root is said to be laid out in auto mode.

When a table-root is laid out in fixed mode, 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 § 3.8.3 Computing Column Measures).

3.5.2. The Border-Collapse property

When the border-collapse property has collapse 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 § 3.6.2 Overrides applying in collapsed-borders mode), (see § 3.7 Border-collapsing).

A table-root is said to be laid out in collapsed-borders mode in this case. Otherwise, the table-root is said to be laid out in separated-borders mode.

3.5.2.1. The Border-Spacing property

The lengths specify the distance that separates adjoining cell borders in separated-borders mode, and must not be strictly 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 § 3.8.1 Computing Undistributable Space for details on how this affects the table layout.

3.5.3. The Caption-Side property

This property specifies the position of the caption box with respect to the table grid box. Values have the following meanings:

top

Positions the caption box above the table grid box.

bottom

Positions the caption box below the table grid box.

caption {
  caption-side: bottom;
  width: auto;
  text-align: left
}

3.6. Style overrides

Some css properties behave differently inside css tables. The following sections list the exceptions and their effects.

3.6.1. Overrides applying in all modes

The following rules apply to all tables, irrespective of the layout mode in use.

• The computed values of properties position, float, margin-*, top, right, bottom, and left on the table are used on the table-wrapper box and not the table grid box; the same holds true for the properties whose use could force the used value of transform-style to flat (see list) and their shorthands/longhands relatives: this list currently includes overflow, opacity, filter, clip, clip-path, isolation, mask-*, mix-blend-mode, transform-* and perspective.
  Where the specified values are not applied on the table grid and/or wrapper boxes, the unset values are used instead for that box (inherit or initial, depending on the property).
  Tests

  • caption-relative-positioning.html (live test) (source)
• The overflow property on the table-root and table-wrapper box, when its value is not either visible, clip or hidden, is ignored and treated as if its value was visible.
• All css properties of table-column and table-column-group boxes are ignored, except when explicitly specified by this specification.
• The margin, padding, overflow and z-index of table-track and table-track-group boxes are ignored.
• The margin of table-cell boxes is ignored (as if it was set to 0px).
  Tests

  • no-overflow-with-table-cell-margins.html (live test) (source)
• The background of table-cell boxes are painted using a special background painting algorithm described in § 5.3.2 Drawing cell backgrounds.

3.6.2. Overrides applying in collapsed-borders mode

When a table is laid out in collapsed-borders mode, the following rules apply:

• The padding of the table-root is ignored (as if it was set to 0px).
• The border-spacing of the table-root is ignored (as if it was set to 0px).
• The border-radius of both table-root and table-non-root boxes is ignored (as if it was set to 0px).
• The values used for the layout and rendering of the borders of the table-root and the table-cell boxes it owns are determined using a special conflict resolution algorithm described in § 3.7 Border-collapsing.

3.7. Border-collapsing

border-collapsing breaking change from 2.1 [Issue #604]

3.7.1. Conflict Resolution for Collapsed Borders

When they are laid out in collapsed-borders mode, table-root and table-cell boxes sharing a border attempt to unify their borders so that they render using the same style, width, and color (whenever this is possible). This is accomplished by running the following algorithm.

3.7.1.1. Conflict Resolution Algorithm for Collapsed Borders

For any table-cell C° of a table-root:

• Resolve conflicts with border-right:
  0. Let S be an ordered set of table-cell border styles, sorted by cell in RowStart/ColumnStart order; initially, let S contain only C°’s border-right style
  1. Add to the set S the border-left style of all cells sharing a section of their left border with C°’s right border
  2. Repeat the following two instructions, until no new border style is added to S:
     • For all newly-added left borders from cell C_i having a rowspan greater than one, add to the set S the border-right style of all cells sharing a section of their border-right with C_i’s border-left
     • For all newly-added right borders from cell C_i having a rowspan greater than one, add to the set S the border-left style of all cells sharing a section of their border-left with C_i’s border-right
  3. Harmonize the conflicting borders of S
• Resolve conflicts with border-bottom:
  0. Let S be an ordered set of table-cell border styles, sorted by cell in RowStart/ColumnStart order; initially, let S contain only C°’s border-bottom style
  1. Add to the set S the border-top style of all cells sharing a section of their top border with C°’s bottom border
  2. Repeat the following two instructions, until no new border style is added to S:
     • For all newly-added top borders from cell C_i having a rowspan greater than one, add to the set S the border-bottom style of all cells sharing a section of their bottom border with C_i’s top border
     • For all newly-added bottom borders from cell C_i having a rowspan greater than one, add to the set S the border-top style of all cells sharing a section of their top border with C_i’s bottom border
  3. Harmonize the conflicting borders of S
• Divide the used width of all borders by two.
  
  This effect will be compensated at rendering time wherever needed, but is required for layout correctness. (see § 5.3.3.1 Changes in collapsed-borders mode)

Then, for that table-root:

• Harmonize the table-root border-{top,bottom,left,right} with the corresponding border of all cells forming the border of the table (independently), without actually modifying the border properties of the table-root.
  
  If the table and the cell border styles have the same specificity, keep the cell border style.
  Once this is done, set the table-root border-{…}-width to half the maximum width found during the harmonization processes for that border, then set border-{…}-style to solid, and border-{…}-color to transparent.

3.7.1.2. Harmonization Algorithm for Collapsed Borders

Change specificity in harmonization of collapsed borders? [Issue #606]

Given an ordered set of border styles (BC_1, BC₂, … located in cells C_1, C₂, …) execute the following algorithm to determine the used value of the border properties for those conflicting borders.

• Set CurrentlyWinningBorderProperties to “border: 0px none transparent”
• For each border BC_i:
  • Consider the BC_i border’s properties
• If the border separates two columns:
  • For each border BC_i: For each table-column spanned by the C_i cell, if any. Consider the border’s properties of any border of the table-column that would be drawn contiguously to BC_i.
  • For each border BC_i: For each table-column-group containing a column spanned by the C_i cell, if any. Consider the border’s properties of any border of the table-column-group that would be drawn contiguously to BC_i.
• If the border separates two rows:
  • For each border BC_i: For each table-row spanned by the C_i cell, if any. Consider the border’s properties of any border of the table-column that would be drawn contiguously to BC_i.
  • For each border BC_i: For each table-row-group containing a column spanned by the C_i cell, if any. Consider the border’s properties of any border of the table-row-group that would be drawn contiguously to BC_i.
• Return CurrentlyWinningBorderProperties

3.7.1.3. Specificity of a border style

Given two borders styles, the border style having the most specificity is the border style which…

1. … has the value "hidden" as border-style, if only one does
2. … has the biggest border-width, once converted into css pixels
3. … has the border-style which comes first in the following list:

   double, solid, dashed, dotted, ridge, outset, groove, inset, none

If none of these criterion matches, then both borders share the same specificity.

3.8. Computing table measures

3.8.1. Computing Undistributable Space

The undistributable space of the table is the sum of the distances between the borders of consecutive table-cells (and between the border of the table-root and the table-cells).

The distance between the borders of two consecutive table-cells is the border-spacing, if any.

The distance between the table border and the borders of the cells on the edge of the table is the table’s padding for that side, plus the relevant border spacing distance (if any).

3.8.2. Computing Cell Measures

The following terms are parameters of tables or table cells. These parameters encapsulate the differences between tables with different values of border-collapse (separate or collapse) so that the remaining subsections of this section do not need to refer to them differently.

cell intrinsic offsets

The cell intrinsic offsets is a term to capture the parts of padding and border of a table cell that are relevant to intrinsic width calculation. It is a set of computed values for border-left-width, padding-left, padding-right, and border-right-width (along with zero values for margin-left and margin-right) defined as follows:

• In separated-borders mode: the computed horizontal padding and border of the table-cell
• In collapsed-borders mode: the computed horizontal padding of the cell and, for border values, the used border-width values of the cell (half the winning border-width)

table intrinsic offsets

The table intrinsic offsets capture the parts of the padding and border of a table that are relevant to intrinsic width calculation. It is a set of computed values for border-left-width, padding-left, padding-right, and border-right-width (along with zero values for margin-left and margin-right) defined as follows:

• In separated-borders mode: the computed horizontal padding and border of the table-root
• In collapsed-borders mode: the used border-width values of the cell (half the winning border-width)

The margins are not included in the table intrinsic offsets because handling of margins depends on the caption-side property.

Handling of intrinsic offsets when in border collapsing mode [Issue #608]

total horizontal border spacing

The total horizontal border spacing is defined for each table:

• For tables laid out in separated-borders mode containing at least one column, the horizontal component of the computed value of the border-spacing property times one plus the number of columns in the table
• Otherwise, 0

offsets-adjusted min-width, width, and max-width

• For table-track and table-track-group boxes, the offsets-adjusted value of width properties is their computed value, irrespective of the value of box-sizing applied on the element.
• For table-cell boxes, the offsets-adjusted value of width properties is their computed value from which the cell’s border-{left|right}-width and/or padding-{left|right} have eventually been deduced, depending on the value of box-sizing.
  When the table is laid out in collapsed-borders mode, the border value to deduce is half the value of the winning border value on each side (see conflict resolution explanation note)

Testcase. Testcase. Testcase.

outer min-content and outer max-content widths

The outer min-content and max-content widths are defined for table cells, columns, and column groups. The width, min-width, and max-width values used in these definitions are the offsets-adjusted values defined above:

• The outer min-content width of a table-cell is max(min-width, min-content width) adjusted by the cell intrinsic offsets.
• The outer min-content width of a table-column or table-column-group is max(min-width, width).
• The outer max-content width of a table-cell in a non-constrained column is max(min-width, width, min-content width, min(max-width, max-content width)) adjusted by the cell intrinsic offsets.
• The outer max-content width of a table-cell in a constrained column is max(min-width, width, min-content width, min(max-width, width)) adjusted by the cell intrinsic offsets.
• The outer max-content width of a table-column or table-column-group is max(min-width, min(max-width, width)).

percentage contributions

The percentage contribution of a table cell, column, or column group is defined in terms of the computed values of width and max-width that have computed values that are percentages:

min(percentage width, percentage max-width).

If the computed values are not percentages, then 0% is used for width, and an infinite percentage is used for max-width.

Please note that min-width is not included in this computation. As a result, a percentage min-width is ignored. Since width functions like a min-width in table layout and column sizing cannot be both length-based and percent-based, authors should not use min-width on table-internal boxes and prefer to rely on width only instead.

3.8.3. Computing Column Measures

This subsection defines three important values associated with each column of a table: their min-content width (the smallest possible width attributed to this column), their max-content width (the width that would be attributed to the column if no other constraint applied), their intrinsic percentage width (the percentage of the table width the column desires to get, and could end up overriding its max-content width).

To compute these values, an iterative algorithm is used. First, these values are computed ignoring any cell spanning more than one column. Then, these values are updated by taking into account cells spanning incrementally more columns. When cells that spanned all columns of the table have been considered, this algorithm ends and the values are then finalized.

For the purpose of measuring a column when laid out in fixed mode, only cells which originate in the first row of the table (after reordering the header and footer) will be considered, if any. In addition, the min-content and max-content width of cells is considered zero unless they are directly specified as a length-percentage, in which case they are resolved based on the table width (if it is definite, otherwise use 0).

For the purpose of calculating the outer min-content width of cells, descendants of table cells whose width depends on percentages of their parent cell' width are considered to have an auto width. Testcase Testcase

min-content width of a column based on cells of span up to 1

The largest of:

• the width specified for the column:
  • the outer min-content width of its corresponding table-column, if any (and not auto)
  • the outer min-content width of its corresponding table-column-group, if any
  • or 0, if there is none
• the outer min-content width of each cell that spans the column whose colSpan is 1 (or just the one in the first row in fixed mode) or 0 if there is none

max-content width of a column based on cells of span up to 1

The largest of:

• the outer max-content width of its corresponding table-column-group, if any
• the outer max-content width of its corresponding table-column, if any
• the outer max-content width of each cell that spans the column whose colSpan is 1 (or just the one in the first row if in fixed mode) or 0 if there is no such cell

intrinsic percentage width of a column based on cells of span up to 1

The largest of the percentage contributions of each cell that spans the column whose colSpan is 1, of its corresponding table-column (if any), and of its corresponding table-column-group (if any)

min-content width of a column based on cells of span up to N (N > 1)

the largest of the min-content width of the column based on cells of span up to N-1 and the contributions of the cells in the column whose colSpan is N, where the contribution of a cell is the result of taking the following steps:

1. Define the baseline min-content width as the sum of the max-content widths based on cells of span up to N-1 of all columns that the cell spans.
2. Define the baseline border spacing as the sum of the horizontal border-spacing for any columns spanned by the cell, other than the one in which the cell originates.
3. The contribution of the cell is the sum of:
   • the min-content width of the column based on cells of span up to N-1
   • the product of:
     • the ratio of:
       • the max-content width of the column based on cells of span up to N-1 of the column minus the min-content width of the column based on cells of span up to N-1 of the column, to
       • the baseline max-content width minus the baseline min-content width
       or zero if this ratio is undefined, and
     • the outer min-content width of the cell minus the baseline min-content width and the baseline border spacing, clamped to be at least 0 and at most the difference between the baseline max-content width and the baseline min-content width
   • the product of:
     • the ratio of the max-content width based on cells of span up to N-1 of the column to the baseline max-content width
     • the outer min-content width of the cell minus the baseline max-content width and baseline border spacing, or 0 if this is negative

max-content width of a column based on cells of span up to N (N > 1)

The largest of the max-content width based on cells of span up to N-1 and the contributions of the cells in the column whose colSpan is N, where the contribution of a cell is the result of taking the following steps:

1. Define the baseline max-content width as the sum of the max-content widths based on cells of span up to N-1 of all columns that the cell spans.
2. Define the baseline border spacing as the sum of the horizontal border-spacing for any columns spanned by the cell, other than the one in which the cell originates.
3. The contribution of the cell is the sum of:
   • the max-content width of the column based on cells of span up to N-1
   • the product of:
     • the ratio of the max-content width based on cells of span up to N-1 of the column to the baseline max-content width
     • the outer max-content width of the cell minus the baseline max-content width and the baseline border spacing, or 0 if this is negative

intrinsic percentage width of a column based on cells of span up to N (N > 1)

If the intrinsic percentage width of a column based on cells of span up to N-1 is greater than 0%, then the intrinsic percentage width of the column based on cells of span up to N is the same as the intrinsic percentage width of the column based on cells of span up to N-1.

Otherwise, it is the largest of the contributions of the cells in the column whose colSpan is N, where the contribution of a cell is the result of taking the following steps:

1. Start with the percentage contribution of the cell.
2. Subtract the intrinsic percentage width of the column based on cells of span up to N-1 of all columns that the cell spans. If this gives a negative result, change it to 0%.
3. Multiply by the ratio of
   • the column’s non-spanning max-content width to
   • the sum of the non-spanning max-content widths of all columns spanned by the cell that have an intrinsic percentage width of the column based on cells of span up to N-1 equal to 0%.
   However, if this ratio is undefined because the denominator is zero, instead use the 1 divided by the number of columns spanned by the cell that have an intrinsic percentage width of the column based on cells of span up to N-1 equal to zero.

min-content width of a column

the min-content width of the column based on cells of span up to N, where N is the number of columns in the table

max-content width of a column

the max-content width of the column based on cells of span up to N, where N is the number of columns in the table

intrinsic percentage width of a column

the smaller of:

• the intrinsic percentage width of the column based on cells of span up to N, where N is the number of columns in the table
• 100% minus the sum of the intrinsic percentage width of all prior columns in the table (further left when direction is "ltr" (right for "rtl")) Testcase

The clamping of the total of the intrinsic percentage widths of columns to a maximum of 100% means that the table layout algorithm is not invariant under switching of columns.

constrainedness

A column is constrained if its corresponding table-column-group (if any), its corresponding table-column (if any), or any of the cells spanning only that column has a computed width that is not "auto", and is not a percentage.

3.9. Available Width Distribution

3.9.1. Computing the table width

Before deciding on the final width of all columns, it is necessary to compute the width of the table itself.

As noted before, this would usually be the sum of preferred width of all columns, plus any extra. In this case, the width distribution will result in giving each column its preferred width. There are however a few cases where the author asks for some other width explicitly, as well as a few cases where the table cannot be given the width it requires.

The caption width minimum (CAPMIN) is the largest of the table captions min-content contribution.

The row/column-grid width minimum (GRIDMIN) width is the sum of the min-content width of all the columns plus cell spacing or borders.

The row/column-grid width maximum (GRIDMAX) width is the sum of the max-content width of all the columns plus cell spacing or borders.

The used min-width of a table is the greater of the resolved min-width, CAPMIN, and GRIDMIN.

The used width of a table depends on the columns and captions widths as follows:

• If the table-root’s width property has a computed value (resolving to resolved-table-width) other than auto, the used width is the greater of resolved-table-width, and the used min-width of the table.
  If the used width is greater than GRIDMIN, the extra width should be distributed over the columns. See § 3.9 Available Width Distribution.
• If the table-root has 'width: auto', the used width is the greater of min(GRIDMAX, the table’s containing block width), the used min-width of the table.

The assignable table width is the used width of the table minus the total horizontal border spacing (if any). This is the width that we will be able to allocate to the columns.