This document describes a new table layout algorithm, to work alongside the existing auto and fixed table layout algorithms. While it is designed for use with the Template Layout draft and element with display:template, it can also be used with any element with display:table, via the table-layout property.

Overview

The template table layout algorithm is designed to be simple and useful for laying out website designs.

It is based entirely on specifying the size of rows and columns, not individual cells. This makes the constraints involved in the algorithm simpler to understand and specify. The contents of cells can still affect the algorithm by influencing the height and width of rows and columns, but explicit width or height declarations on individual cells are ignored.

Allowed Values

In the template table-layout algorithm, table rows may have the following values for height:

<length> : An explicit height for that row. Negative values make the template illegal.

<percentage> : An explicit percentage height for that row. If the element being laid out doesn't have an a-priori height, this is instead a percentage of the height of the element's initial containing block.

auto : The row's height is determined by its contents. See the algorithm below.

* : (asterisk) All rows with an asterisk will be of equal height. See the algorithm below.

any other value : The row's height resolves to 'auto'.

Table columns may have the following values for width:

<length> : An explicit width for that column. Negative values make the template illegal.

<percentage> : An explicit percentage width for that column. If the element being laid out doesn't have an a-priori width, this is instead a percentage of the height of the element's initial containing block.

* : (asterisk.) All columns with a * have the same width. See the algorithm below.

max-content or min-content : The column's width is determined by its contents. See the algorithm below.

minmax(p,q) : The column's width is constrained to be greater than or equal to p and less than or equal to q. p and q stand for [ <length> | max-content | min-content | * ]. There may be white space around the p and q. If q < p, then q is ignored and minmax(p,q) is treated as minmax(p,p).

fit-content : Equivalent to minmax(min-content, max-content).

Computing the width of the columns

First, the intrinsic minimum widths and intrinsic preferred widths are defined as follows:

• A column with a <col-width> of a given <length> has intrinsic minimum and intrinsic preferred widths both equal to that <length>.

• A column with a <col-width> of * has an infinite intrinsic preferred width. Its intrinsic minimum width is 0.

• A column with a <col-width> of min-content has an intrinsic minimum width and intrinsic preferred width that are both equal to the largest of the intrinsic minimum widths of all the cells in that column:

  • The intrinsic minimum width of a “.” is 0. (This is only relevant for Template Layouts, not ordinary tables.)
  • The intrinsic minimum width of any other cell is 0 if that cell spans two or more columns; otherwise, it is the intrinsic minimum width as defined by [CSS3BOX].

• A column with a <col-width> of max-content has an intrinsic minimum width and intrinsic preferred width that are both equal to the largest of the intrinsic preferred widths of all the slots in that column:

  • The intrinsic preferred width of a “.” is 0. (This is only relevant for Template Layouts, not ordinary tables.)
  • The intrinsic preferred width of any other cell is the intrinsic preferred width as defined by [CSS3BOX].

• A column with a <col-width> of minmax(p,q) has an intrinsic minimum width equal to p and an intrinsic preferred width equal to q.

Next, the layout algorithm distinguishes between elements with and without an a-priori known content width. (The width isn't known a-priori, if, e.g., width is auto and the element is floating, absolutely positioned, inline-block or a child of a block with vertical writing mode.)

If the element has an a-priori width:

• If the sum of the intrinsic minimum widths of the columns is larger than the element's width, each column is set to its intrinsic minimum width and the contents will overflow (see overflow).
• If the sum of the intrinsic minimum widths of the columns is less than or equal to the element's width, the columns are widened until the total width is equal to the element's width, as follows: all columns get the same width, except that no column or span of columns may be wider than its intrinsic preferred width. If the columns cannot be widened enough, the template is left or right aligned in the element's content area, depending on whether direction is ltr or rtl, respectively.

If the element doesn't have an a-priori width:

• If the sum of the intrinsic minimum widths of the columns is wider than the initial containing block, each column is set to its intrinsic minimum width. The element's used width is the sum of the widths of the columns.
• If the sum of the intrinsic minimum widths of the columns is less than or equal to the width of the initial containing block, the columns are widened until the total width is equal to the initial containing block, as follows: all columns get the same width, except that no column or span of columns may be wider than its maximum intrinsic width. The element's used width is the sum of the widths of the columns.

Computing the height of the rows

The combined height of all rows is the smallest possible under the following constraints:

• Rows with a height set to <length> or <percentage> have that height.
• No row has a negative height.
• All rows with a height set to * are the same height.
• Every sequence of one or more rows of which at least one has a height set to auto is at least as high as every cell that spans exactly that sequence of rows.
• If the computed value of the element's height is auto, then every sequence of one or more rows of which at least one has a height set to * is at least as high as every cell that spans exactly that sequence of rows.
• The combined height of all rows is at least as high as the computed value of the element's height, unless that value is auto, or unless all rows have a height set to <length> or <percentage>.

If any rows must be made taller in order to satisfy the last rule than they would be without the last rule, then all rows with auto or * heights must have their heights increased as equally as possible when satisfying the last rule.

If the combined height of all rows is higher than the element's height, the element overflows.