Tabular data

The table element

Categories:
Flow content.
Palpable content.
Contexts in which this element can be used:
Where flow content is expected, but with no caption element ancestors.
Content model:
In this order: optionally a <{caption}> element, followed by zero or more <{colgroup}> elements, followed optionally by a <{thead}> element, followed by either zero or more <{tbody}> elements or one or more <{tr}> elements, followed optionally by a <{tfoot}> element, optionally intermixed with one or more script-supporting elements.
Tag omission in text/html:
Neither tag is omissible
Content attributes:
Global attributes
border
[=Allowed ARIA role attribute values=]:
table role (default - do not set) or Any other role value.
[=Allowed ARIA state and property attributes=]:
Global aria-* attributes
Any aria-* attributes applicable to the allowed roles.
DOM interface:
        interface HTMLTableElement : HTMLElement {
          attribute HTMLTableCaptionElement? caption;
          HTMLTableCaptionElement createCaption();
          void deleteCaption();
          attribute HTMLTableSectionElement? tHead;
          HTMLTableSectionElement createTHead();
          void deleteTHead();
          attribute HTMLTableSectionElement? tFoot;
          HTMLTableSectionElement createTFoot();
          void deleteTFoot();
          [SameObject] readonly attribute HTMLCollection tBodies;
          HTMLTableSectionElement createTBody();
          [SameObject] readonly attribute HTMLCollection rows;
          HTMLTableRowElement insertRow(optional long index = -1);
          void deleteRow(long index);
        };
The <{table}> element represents data with more than one dimension, in the form of a table. The <{table}> element takes part in the table model. Tables have rows, columns, and cells given by their descendants. The rows and columns form a grid; a table's cells must completely cover that grid without overlap.

Precise rules for determining whether this conformance requirement is met are described in the description of the table model.

Authors are encouraged to provide information describing how to interpret complex tables. Guidance on how to provide such information is given below. Tables should not be used as layout aids. Historically, many Web authors have tables in HTML as a way to control their page layout making it difficult to extract tabular data from such documents. In particular, users of accessibility tools, like screen readers, are likely to find it very difficult to navigate pages with tables used for layout. If a table is used for layout purposes, it must be marked with the attribute role="presentation" for a user agent to properly represent the table to an assistive technology, and to properly convey the intent of the author to tools that wish to extract tabular data from the document.

There are a variety of alternatives to using HTML tables for layout, primarily using CSS positioning and the CSS table model. [[!CSS-2015]]

The border content attribute may be specified on a <{table}> element to explicitly indicate that the <{table}> element represents tabular data and is not being used for layout purposes. If specified, the attribute's value must either be the empty string or the value "1". If a value other than the empty string, or "1" is set, such as a text string, user agents should interpret the value as the empty string. The border content attribute is used by certain user agents as an indication that borders should be drawn around cells of the table. These user agents may treat values greater than 1 as indicators to render wider borders for the table. Authors should instead use CSS to provide styling for tables.
Tables can be complicated to understand and navigate. To help users with this, user agents should clearly delineate cells in a table from each other, unless the user agent has classified the table as a layout table.

Authors and implementors are encouraged to consider using some of the table design techniques described below to make tables easier to navigate for users.

User agents, especially those that do table analysis on arbitrary content, are encouraged to find heuristics to determine which tables actually contain data and which are merely being used for layout. This specification does not define a precise heuristic, but the following are suggested as possible indicators:
Feature Indication
The use of the role attribute with the value presentation Probably a layout table
The use of the border attribute with the non-conforming value 0 Probably a layout table
The use of the non-conforming cellspacing and cellpadding attributes with the value 0 Probably a layout table
The use of <{caption}>, <{thead}>, or <{th}> elements Probably a non-layout table
The use of the headers and scope attributes Probably a non-layout table
The use of the border attribute with a value other than 0 Probably a non-layout table
Explicit visible borders set using CSS Probably a non-layout table
The use of the non-conforming summary attribute Not a good indicator (both layout and non-layout tables have historically been given this attribute)

It is quite possible that the above suggestions are wrong. Implementors are urged to provide feedback elaborating on their experiences with trying to create a layout table detection heuristic.

If a <{table}> element has a (non-conforming) summary attribute, and the user agent has not classified the table as a layout table, the user agent may report the contents of that attribute to the user.
table . caption [ = value ]
Returns the table's <{caption}> element. Can be set, to replace the <{caption}> element.
caption = table . createCaption()
Ensures the table has a <{caption}> element, and returns it.
table . deleteCaption()
Ensures the table does not have a <{caption}> element.
table . tHead [ = value ]
Returns the table's <{thead}> element. Can be set, to replace the <{thead}> element. If the new value is not a <{thead}> element, throws a {{HierarchyRequestError}} exception.
thead = table . createTHead()
Ensures the table has a <{thead}> element, and returns it.
table . deleteTHead()
Ensures the table does not have a <{thead}> element.
table . tFoot [ = value ]
Returns the table's <{tfoot}> element. Can be set, to replace the <{tfoot}> element. If the new value is not a <{tfoot}> element, throws a {{HierarchyRequestError}} exception.
tfoot = table . createTFoot()
Ensures the table has a <{tfoot}> element, and returns it.
table . deleteTFoot()
Ensures the table does not have a <{tfoot}> element.
table . tBodies
Returns an HTMLCollection of the <{tbody}> elements of the table.
tbody = table . createTBody()
Creates a <{tbody}> element, inserts it into the table, and returns it.
table . rows
Returns an HTMLCollection of the <{tr}> elements of the table.
tr = table . insertRow( [ index ] )
Creates a <{tr}> element, along with a tbody if required, inserts them into the table at the position given by the argument, and returns the <{tr}>. The position is relative to the rows in the table. The index -1, which is the default if the argument is omitted, is equivalent to inserting at the end of the table. If the given position is less than -1 or greater than the number of rows, throws an {{IndexSizeError}} exception.
table . deleteRow(index)
Removes the <{tr}> element with the given position in the table. The position is relative to the rows in the table. The index -1 is equivalent to deleting the last row of the table. If the given position is less than -1 or greater than the index of the last row, or if there are no rows, throws an {{IndexSizeError}} exception.
The caption IDL attribute must return, on getting, the first <{caption}> element child of the <{table}> element, if any, or null otherwise. On setting, the first <{caption}> element child of the <{table}> element, if any, must be removed, and the new value, if not null, must be inserted as the first node of the <{table}> element. The createCaption() method must return the first <{caption}> element child of the <{table}> element, if any; otherwise a new <{caption}> element must be created, inserted as the first node of the <{table}> element, and then returned. The deleteCaption() method must remove the first <{caption}> element child of the <{table}> element, if any. The tHead IDL attribute must return, on getting, the first <{thead}> element child of the <{table}> element, if any, or null otherwise. On setting, if the new value is null or a <{thead}> element, the first <{thead}> element child of the <{table}> element, if any, must be removed, and the new value, if not null, must be inserted immediately before the first element in the <{table}> element that is neither a <{caption}> element nor a <{colgroup}> element, if any, or at the end of the table if there are no such elements. If the new value is neither null nor a <{thead}> element, then a {{HierarchyRequestError}} DOM exception must be thrown instead. The createTHead() method must return the first <{thead}> element child of the <{table}> element, if any; otherwise a new <{thead}> element must be created and inserted immediately before the first element in the <{table}> element that is neither a <{caption}> element nor a <{colgroup}> element, if any, or at the end of the table if there are no such elements, and then that new element must be returned. The deleteTHead() method must remove the first <{thead}> element child of the <{table}> element, if any. The tFoot IDL attribute must return, on getting, the first <{tfoot}> element child of the <{table}> element, if any, or null otherwise. On setting, if the new value is null or a <{tfoot}> element, the first <{tfoot}> element child of the <{table}> element, if any, must be removed, and the new value, if not null, must be inserted at the end of the table. If the new value is neither null nor a <{tfoot}> element, then a {{HierarchyRequestError}} DOM exception must be thrown instead. The createTFoot() method must return the first <{tfoot}> element child of the <{table}> element, if any; otherwise a new <{tfoot}> element must be created and inserted at the end of the table, and then that new element must be returned. The deleteTFoot() method must remove the first <{tfoot}> element child of the <{table}> element, if any. The tBodies attribute must return an HTMLCollection rooted at the table node, whose filter matches only <{tbody}> elements that are children of the <{table}> element. The createTBody() method must create a new <{tbody}> element, insert it immediately after the last <{tbody}> element child in the <{table}> element, if any, or at the end of the <{table}> element if the <{table}> element has no <{tbody}> element children, and then must return the new <{tbody}> element. The rows attribute must return an HTMLCollection rooted at the table node, whose filter matches only <{tr}> elements that are either children of the <{table}> element, or children of <{thead}>, <{tbody}>, or <{tfoot}> elements that are themselves children of the <{table}> element. The elements in the collection must be ordered such that those elements whose parent is a thead are included first, in tree order, followed by those elements whose parent is either a table or tbody element, again in tree order, followed finally by those elements whose parent is a tfoot element, still in tree order. The behavior of the insertRow(index) method depends on the state of the table. When it is called, the method must act as required by the first item in the following list of conditions that describes the state of the table and the index argument:
If index is less than -1 or greater than the number of elements in rows collection:
The method must throw an {{IndexSizeError}} exception.
If the rows collection has zero elements in it, and the table has no <{tbody}> elements in it:
The method must create a <{tbody}> element, then create a <{tr}> element, then append the <{tr}> element to the <{tbody}> element, then append the <{tbody}> element to the <{table}> element, and finally return the <{tr}> element.
If the rows collection has zero elements in it:
The method must create a <{tr}> element, append it to the last tbody element in the table, and return the <{tr}> element.
If index is -1 or equal to the number of items in rows collection:
The method must create a <{tr}> element, and append it to the parent of the last <{tr}> element in the rows collection. Then, the newly created <{tr}> element must be returned.
Otherwise:
The method must create a <{tr}> element, insert it immediately before the indexth <{tr}> element in the rows collection, in the same parent, and finally must return the newly created tr element.
When the deleteRow(index) method is called, the user agent must run the following steps:
  1. If index is equal to -1, then index must be set to the number of items in the rows collection, minus one.
  2. Now, if index is less than zero, or greater than or equal to the number of elements in the rows collection, the method must instead throw an {{IndexSizeError}} exception, and these steps must be aborted.
  3. Otherwise, the method must remove the indexth element in the rows collection from its parent.
Here is an example of a table being used to mark up a game of Tic-tac-toe. Note the lack of headers, which are not necessary in such a table. <table> <tbody> <tr> <td>X</td> <td>X</td> <td>0</td> </tr> <tr> <td>0</td> <td>X</td> <td>0</td> </tr> <tr> <td>X</td> <td>0</td> <td> </td> </tr> </tbody> </table>
Techniques for describing tables
For tables that consist of more than just a grid of cells with headers in the first row and headers in the first column, and for any table in general where the reader might have difficulty understanding the content, authors should include explanatory information introducing the table. This information is useful for all users, but is especially useful for users who cannot see the table, e.g., users of screen readers. Such explanatory information should introduce the purpose of the table, outline its basic cell structure, highlight any trends or patterns, and generally teach the user how to understand the contents of the table. For instance, the following table:
Characteristics with positive and negative sides
Negative Characteristic Positive
Sad Mood Happy
Failing Grade Passing
...could benefit from a description explaining the way the table is laid out, something like "Characteristics are given in the second column, with the negative side in the left column and the positive side in the right column". There are a variety of ways to include this information, such as:
In prose, surrounding the table
<p id="summary"> In the following table, characteristics are given in the second column, with the negative side in the left column and the positive side in the right column. </p> <table aria-describedby="summary"> <caption>Characteristics with positive and negative sides</caption> <thead> <tr> <th id="n"> Negative </th> <th> Characteristic </th> <th> Positive </th> </tr> </thead> <tbody> <tr> <td headers="n r1"> Sad </td> <th id="r1"> Mood </th> <td> Happy </td> </tr> <tr> <td headers="n r2"> Failing </td> <th id="r2"> Grade </th> <td> Passing </td> </tr> </table>

In the example above the <{aria/aria-describedby}> attribute is used to explicitly associate the information with the table for assistive technology users.

Next to the table, in the same figure
<figure aria-labelledby="caption"> <p> Characteristics are given in the second column, with the negative side in the left column and the positive side in the right column. </p> <table> <caption id="caption">Characteristics with positive and negative sides</caption> <thead> <tr> <th id="n"> Negative </th> <th> Characteristic </th> <th> Positive </th> </tr> </thead> <tbody> <tr> <td headers="n r1"> Sad </td> <th id="r1"> Mood </th> <td> Happy </td> </tr> <tr> <td headers="n r2"> Failing </td> <th id="r2"> Grade </th> <td> Passing </td> </tr> </table> </figure>

The <{figure}> in this example has been labeled by the table <{caption}> using <{aria/aria-labelledby}>.

Authors may also use other techniques, or combinations of the above techniques, as appropriate.

Regardless of the method used to provide additional descriptive information for a table, if a <{table}> needs a caption, authors should use a <{caption}> element as it is the most robust method for providing an accessible caption for a table.

The best option, of course, rather than writing a description explaining the way the table is laid out, is to adjust the table such that no explanation is needed.
In the case of the table used in the examples above, a simple rearrangement of the table so that the headers are on the top and left sides removes the need for an explanation as well as removing the need for the use of headers attributes: <table> <caption>Characteristics with positive and negative sides</caption> <thead> <tr> <th> Characteristic </th> <th> Negative </th> <th> Positive </th> </tr> <tbody> <tr> <th> Mood </th> <td> Sad </td> <td> Happy </td> </tr> <tr> <th> Grade </th> <td> Failing </td> <td> Passing </td> </tr> </tbody> </table>
Techniques for table design
Good table design is key to making tables more readable and usable. In visual media, providing column and row borders and alternating row backgrounds can be very effective to make complicated tables more readable. For tables with large volumes of numeric content, using monospaced fonts can help users see patterns, especially in situations where a user agent does not render the borders. (Unfortunately, for historical reasons, not rendering borders on tables is a common default.) Authors are encouraged to use CSS to achieve these visual effects. In speech media, table cells can be distinguished by reporting the corresponding headers before reading the cell's contents, and by allowing users to navigate the table in a grid fashion, rather than serializing the entire contents of the table in source order. User agents are encouraged to render tables using these techniques whenever the page does not use CSS and the table is not classified as a layout table.

The caption element

Categories:
None.
Contexts in which this element can be used:
As the first element child of a <{table}> element.
Content model:
Flow content, but with no <{main}>, or <{table}> element descendants.
Tag omission in text/html:
A <{caption}> element's end tag may be omitted.
Content attributes:
Global attributes
[=Allowed ARIA role attribute values=]:
None
[=Allowed ARIA state and property attributes=]:
Global aria-* attributes
DOM interface:
        interface HTMLTableCaptionElement : HTMLElement {};

If the closing tag is omitted, the element will be closed by the next element that takes part in the table model. Content up to that element will be part of the caption.

The <{caption}> element represents the title of the table that is its parent, if it has a parent and that is a <{table}> element. The <{caption}> element takes part in the table model. When a <{table}> element is the only content in a <{figure}> element other than the <{figcaption}>, the <{caption}> element should be omitted in favor of the <{figcaption}>. As noted in [[#sec-techniques-for-describing-tables|techniques for describing tables]], a caption is the most robust method for providing an accessible caption to a table. A caption can introduce context for a table, making it significantly easier to understand.
Consider, for instance, the following table:
1 2 3 4 5 6
1 2 3 4 5 6 7
2 3 4 5 6 7 8
3 4 5 6 7 8 9
4 5 6 7 8 9 10
5 6 7 8 9 10 11
6 7 8 9 10 11 12
In the abstract, this table is not clear. However, with a caption giving the table's number (for reference in the main prose) and explaining its use, it makes more sense: <table> <caption> Table 1. This table shows the total score obtained from rolling two six-sided dice. The first row represents the value of the first die, the first column the value of the second die. The total is given in the cell that corresponds to the values of the two dice. </caption> <tbody> <!-- ... --> </tbody> </table> This provides the user with more context:
Table 1. This table shows the total score obtained from rolling two six-sided dice. The first row represents the value of the first die, the first column the value of the second die. The total is given in the cell that corresponds to the values of the two dice.
1 2 3 4 5 6
1 2 3 4 5 6 7
2 3 4 5 6 7 8
3 4 5 6 7 8 9
4 5 6 7 8 9 10
5 6 7 8 9 10 11
6 7 8 9 10 11 12

The colgroup element

Categories:
None.
Contexts in which this element can be used:
As a child of a <{table}> element, after any <{caption}> elements and before any <{thead}>, <{tbody}>, <{tfoot}>, and tr elements.
Content model:
If the span attribute is present: Nothing.
If the span attribute is absent: Zero or more col and <{template}> elements.
Tag omission in text/html:
A <{colgroup}> element's [=start tag=] may be omitted if the first thing inside the <{colgroup}> element is a <{col}> element, and if the element is not immediately preceded by another <{colgroup}> element whose [=end tag=] has been omitted. (It can't be omitted if the element is empty). A <{colgroup}> element's end tag may be omitted if the <{colgroup}> element is not immediately followed by a space character or a comment
Content attributes:
Global attributes
span - Number of columns spanned by the element
[=Allowed ARIA role attribute values=]:
None
[=Allowed ARIA state and property attributes=]:
None
DOM interface:
        interface HTMLTableColElement : HTMLElement {
          attribute unsigned long span;
        };
The <{colgroup}> element represents a group of one or more columns in the table that is its parent, if it has a parent and that is a <{table}> element. If the <{colgroup}> element contains no <{col}> elements, then the element may have a span content attribute specified, whose value must be a valid non-negative integer greater than zero. The <{colgroup}> element and its span attribute take part in the table model. The span IDL attribute must reflect the content attribute of the same name. The value must be limited to only non-negative numbers greater than zero.
The following example shows how a <{colgroup}> consisting of three <{col}> elements can utilize CSS to help visually format the columns of a <{table}>. <table style="width: 100%;"> <colgroup style="background: #ccc;"> <col style="background: #ddd; width: 30%;"> <col style="background: #eee; width: 50%;"> <col style="width: 20%;"> </colgroup> <tbody> <tr> <td>...</td> <td>...</td> <td>...</td> </tr> <!-- ... --> </tbody> </table> The next example shows how a <{colgroup}> with no child <{col}> elements can use the <{colgroup/span}> attribute. The applied CSS will render the first two columns with a background color, and set their width to 25%, leaving the last column with no background color, and taking up the remaining width of the <{table}>. <table style="width: 100%;"> <colgroup style="background: #eee; width: 25%;" span="2"></colgroup> <tbody> <tr> <td>...</td> <td>...</td> <td>...</td> </tr> <!-- ... --> </tbody> </table>

The col element

Categories:
None.
Contexts in which this element can be used:
As a child of a <{colgroup}> element that doesn't have a span attribute.
Content model:
Nothing.
Tag omission in text/html:
No end tag.
Content attributes:
Global attributes
span
[=Allowed ARIA role attribute values=]:
None
[=Allowed ARIA state and property attributes=]:
None
DOM interface:
{{HTMLTableColElement}}, same as for <{colgroup}> elements. This interface defines one member, {{HTMLTableColElement/span}}.
If a <{col}> element has a parent and that is a <{colgroup}> element that itself has a parent that is a <{table}> element, then the <{col}> element represents one or more columns in the column group represented by that <{colgroup}>. The element may have a span content attribute specified, whose value must be a valid non-negative integer greater than zero. The <{col}> element and its span attribute take part in the table model. The {{HTMLTableColElement/span}} IDL attribute must reflect the content attribute of the same name. The value must be limited to only non-negative numbers greater than zero.

For examples of the <{col}> element, refer to the examples within the <{colgroup}> section, and the section for table examples.

The tbody element

Categories:
None.
Contexts in which this element can be used:
As a child of a <{table}> element, after any <{caption}>, <{colgroup}>, and <{thead}> elements, but only if there are no <{tr}> elements that are children of the <{table}> element.
Content model:
Zero or more tr and script-supporting elements.
Tag omission in text/html:
A <{tbody}> element's start tag may be omitted if the first thing inside the <{tbody}> element is a <{tr}> element, and if the element is not immediately preceded by a <{tbody}>, <{thead}>, or <{tfoot}> element whose end tag has been omitted. (It can't be omitted if the element is empty.). A <{tbody}> element's end tag may be omitted if the <{tbody}> element is immediately followed by a tbody or <{tfoot}> element, or if there is no more content in the parent element.
Content attributes:
Global attributes
[=Allowed ARIA role attribute values=]:
rowgroup role (default - do not set) or Any other role value.
[=Allowed ARIA state and property attributes=]:
Global aria-* attributes
Any aria-* attributes applicable to the default or allowed roles.
DOM interface:
        interface HTMLTableSectionElement : HTMLElement {
          [SameObject] readonly attribute HTMLCollection rows;
          HTMLElement insertRow(optional long index = -1);
          void deleteRow(long index);
        };
The {{HTMLTableSectionElement}} interface is also used for <{thead}> and <{tfoot}> elements.
The <{tbody}> element represents a block of rows that consist of a body of data for the parent <{table}> element, if the <{tbody}> element has a parent and it is a <{table}>. The <{tbody}> element takes part in the table model.

For examples of the <{tbody}> element, refer to the <{table}> examples within techniques for describing tables, and the section for table examples.

tbody . rows
Returns an HTMLCollection of the <{tr}> elements of the table section.
tr = tbody . insertRow( [ index ] )
Creates a <{tr}> element, inserts it into the table section at the position given by the argument, and returns the <{tr}>. The position is relative to the rows in the table section. The index -1, which is the default if the argument is omitted, is equivalent to inserting at the end of the table section. If the given position is less than -1 or greater than the number of rows, throws an {{IndexSizeError}} exception.
tbody . deleteRow(index)
Removes the <{tr}> element with the given position in the table section. The position is relative to the rows in the table section. The index -1 is equivalent to deleting the last row of the table section. If the given position is less than -1 or greater than the index of the last row, or if there are no rows, throws an {{IndexSizeError}} exception.
The rows attribute must return an HTMLCollection rooted at the element, whose filter matches only tr elements that are children of the element. The insertRow(index) method must, when invoked on an element table section, act as follows: If index is less than -1 or greater than the number of elements in the rows collection, the method must throw an {{IndexSizeError}} exception. If index is -1 or equal to the number of items in the rows collection, the method must create a <{tr}> element, append it to the element table section, and return the newly created <{tr}> element. Otherwise, the method must create a <{tr}> element, insert it as a child of the table section element, immediately before the indexth <{tr}> element in the rows collection, and finally must return the newly created <{tr}> element. The deleteRow(index) method must, when invoked, act as follows: If index is less than -1 or greater than the number of elements in the rows collection, the method must throw an {{IndexSizeError}} exception. If index is -1, remove the last element in the rows collection from its parent. Otherwise, remove the indexth element in the rows collection from its parent.

The thead element

Categories:
None.
Contexts in which this element can be used:
As a child of a <{table}> element, after any <{caption}>, and colgroup elements and before any <{tbody}>, <{tfoot}>, and <{tr}> elements, but only if there are no other <{thead}> elements that are children of the <{table}> element.
Content model:
Zero or more tr and script-supporting elements.
Tag omission in text/html:
A <{thead}> element's end tag may be omitted if the <{thead}> element is immediately followed by a tbody or <{tfoot}> element.
Content attributes:
Global attributes
[=Allowed ARIA role attribute values=]:
rowgroup role (default - do not set) or Any other role value.
[=Allowed ARIA state and property attributes=]:
Global aria-* attributes
Any aria-* attributes applicable to the default or allowed roles.
DOM interface:
{{HTMLTableSectionElement}}, as defined for <{tbody}> elements.
The <{thead}> element represents the block of rows that consist of the column labels (headers) for the parent <{table}> element, if the thead element has a parent and it is a <{table}>. The <{thead}> element takes part in the table model.
This example shows a <{thead}> element being used. Notice the use of the <{th}> element to provide headers in the thead element: <table border="1"> <caption> School auction sign-up sheet </caption> <thead> <tr> <th><label for="e1">Sellers Name</label></th> <th><label for="e2">Product for sale</label></th> <th><label for="e3">Picture of product</label></th> <th><label for="e4">Reserve Price</label></th> </tr> </thead> <tbody> <tr> <td>Ms Danus</td> <td>Doughnuts</td> <td><img src="https://example.com/mydoughnuts.png" alt="a wide variety of donuts flavors organized into multiple boxes of a dozen donuts"></td> <td>$45</td> </tr> <tr> <td><input id="e1" name="who" required form="f" type="text"></td> <td><input id="e2" name="what" required form="f" type="text"></td> <td><input id="e3" name="pic" form="f" type="url"></td> <td><input id="e4" step="0.01" min="0" value="0" required form="f" type="number"></td> </tr> </tbody> </table>

The tfoot element

Categories:
None.
Contexts in which this element can be used:
As a child of a <{table}> element, after any <{caption}>, <{colgroup}>, <{thead}>, <{tbody}>, and <{tr}> elements, but only if there are no other <{tfoot}> elements that are children of the <{table}> element.
Content model:
Zero or more tr and script-supporting elements.
Tag omission in text/html:
A <{tfoot}> element's end tag may be omitted if there is no more content in the parent <{table}> element.
Content attributes:
Global attributes
[=Allowed ARIA role attribute values=]:
rowgroup role (default - do not set) or Any other role value.
[=Allowed ARIA state and property attributes=]:
Global aria-* attributes
Any aria-* attributes applicable to the default or allowed roles.
DOM interface:
{{HTMLTableSectionElement}}, as defined for <{tbody}> elements.
The <{tfoot}> element represents the block of rows that consist of the column summaries (footers) for the parent <{table}> element, if the <{tfoot}> element has a parent and it is a <{table}>. The <{tfoot}> element takes part in the table model.
The following example uses a <{tfoot}> to indicate a summary of the total monthly spending, earnings, and holdings. 
      <table>
        <thead>
          <tr>
            <th scope="col">Month</th>
            <th scope="col">Spending</th>
            <th scope="col">Earnings</th>
            <th scope="col">Holdings</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <th scope="row">January</th>
            <td>$800</td>
            <td>$700</td>
            <td>-$100</td>
          </tr>
          <tr>
            <th scope="row">February</th>
            <td>$900</td>
            <td>$935</td>
            <td>+$35</td>
          </tr>
        </tbody>
        <tfoot>
          <tr>
            <th scope="row">Totals</th>
            <td>$1,700</td>
            <td>$1,635</td>
            <td>-$65</td>
          </tr>
        </tfoot>
      </table>

The tr element

Categories:
None.
Contexts in which this element can be used:
As a child of a <{thead}> element.
As a child of a <{tbody}> element.
As a child of a <{tfoot}> element.
As a child of a <{table}> element, after any <{caption}>, <{colgroup}>, and <{thead}> elements, but only if there are no <{tbody}> elements that are children of the <{table}> element.
Content model:
Zero or more <{td}>, <{th}>, and script-supporting elements.
Tag omission in text/html:
A <{tr}> element's end tag may be omitted if the <{tr}> element is immediately followed by another <{tr}> element, or if there is no more content in the parent element.
Content attributes:
Global attributes
[=Allowed ARIA role attribute values=]:
row role (default - do not set) or Any other role value.
[=Allowed ARIA state and property attributes=]:
Global aria-* attributes
Any aria-* attributes applicable to the default or allowed roles.
DOM interface:
        interface HTMLTableRowElement : HTMLElement {
          readonly attribute long rowIndex;
          readonly attribute long sectionRowIndex;
          [SameObject] readonly attribute HTMLCollection cells;
          HTMLElement insertCell(optional long index = -1);
          void deleteCell(long index);
        };
The <{tr}> element represents a row of cells in a table. The <{tr}> element takes part in the table model.
tr . rowIndex
Returns the position of the row in the table's rows list. Returns -1 if the element isn't in a table.
tr . sectionRowIndex
Returns the position of the row in the table section's rows list. Returns -1 if the element isn't in a table section.
tr . cells
Returns an HTMLCollection of the td and <{th}> elements of the row.
cell = tr . insertCell( [ index ] )
Creates a <{td}> element, inserts it into the table row at the position given by the argument, and returns the <{td}>. The position is relative to the cells in the row. The index -1, which is the default if the argument is omitted, is equivalent to inserting at the end of the row. If the given position is less than -1 or greater than the number of cells, throws an {{IndexSizeError}} exception.
tr . deleteCell(index)
Removes the td or <{th}> element with the given position in the row. The position is relative to the cells in the row. The index -1 is equivalent to deleting the last cell of the row. If the given position is less than -1 or greater than the index of the last cell, or if there are no cells, throws an {{IndexSizeError}} exception.
The rowIndex attribute must, if the element has a parent <{table}> element, or a parent <{tbody}>, <{thead}>, or <{tfoot}> element and a grandparent <{table}> element, return the index of the <{tr}> element in that <{table}> element's rows collection. If there is no such <{table}> element, then the attribute must return -1. The sectionRowIndex attribute must, if the element has a parent <{table}>, <{tbody}>, <{thead}>, or <{tfoot}> element, return the index of the <{tr}> element in the parent element's rows collection (for tables, that's the HTMLTableElement.rows collection; for table sections, that's the HTMLTableRowElement.rows collection). If there is no such parent element, then the attribute must return -1. The cells attribute must return an HTMLCollection rooted at the <{tr}> element, whose filter matches only td and <{th}> elements that are children of the <{tr}> element. The insertCell(index) method must act as follows: If index is less than -1 or greater than the number of elements in the cells collection, the method must throw an {{IndexSizeError}} exception. If index is equal to -1 or equal to the number of items in cells collection, the method must create a <{td}> element, append it to the <{tr}> element, and return the newly created td element. Otherwise, the method must create a <{td}> element, insert it as a child of the <{tr}> element, immediately before the indexth td or <{th}> element in the cells collection, and finally must return the newly created <{td}> element. The deleteCell(index) method must act as follows: If index is less than -1 or greater than the number of elements in the cells collection, the method must throw an {{IndexSizeError}} exception. If index is -1, remove the last element in the cells collection from its parent. Otherwise, remove the indexth element in the cells collection from its parent.

For examples of the <{tr}> element, refer to the <{table}> examples within [[#sec-techniques-for-describing-tables|techniques for describing tables]], and the section for table examples.

The td element

Categories:
Sectioning root.
Contexts in which this element can be used:
As a child of a <{tr}> element.
Content model:
Flow content but with no <{main}> element descendant.
Tag omission in text/html:
A <{td}> element's end tag may be omitted if the element is immediately followed by another td element or <{th}> element, or if there is no more content in the parent element.
Content attributes:
Global attributes
colspan - Number of columns that the cell is to span
rowspan - Number of rows that the cell is to span
headers - The header cells for this cell
[=Allowed ARIA role attribute values=]:
cell role (default - do not set) or Any other role value.
[=Allowed ARIA state and property attributes=]:
Global aria-* attributes
Any aria-* attributes applicable to the default or allowed roles.
DOM interface:
        interface HTMLTableDataCellElement : HTMLTableCellElement {};
The <{td}> element represents a data cell in a table. The <{td}> element and its colspan, rowspan, and headers attributes take part in the table model. User agents, especially in environments where displaying the table as a 2D grid is impractical, (e.g. in speech output), sometimes add information about a cell when rendering its contents; for instance, giving its position in the table model, or listing its header cells as determined by the algorithm for assigning header cells. When referring to a cell's header cells are being listed, user agents may use the value of <{th/abbr}> to present to the user through a voice interface, instead of the full contents of the header cells themselves. A cell's header cells are determined by the algorithm for Forming relationships between data cells and header cells or can be explicitly defined using the <{td/headers}> attribute.

For examples of the <{td}> element and its content attributes, refer to the <{table}> examples within [[#sec-techniques-for-describing-tables|techniques for describing tables]], and the section for table examples.

The th element

Categories:
None.
Contexts in which this element can be used:
As a child of a <{tr}> element.
Content model:
Flow content, but with no <{header}>, <{footer}>, <{main}>, sectioning content, or heading content descendants.
Tag omission in text/html:
A <{th}> element's end tag may be omitted if the <{th}> element is immediately followed by a <{td}> or <{th}> element, or if there is no more content in the parent element.
Content attributes:
Global attributes
<{tablecells/colspan}> - Number of columns that the cell is to span
<{tablecells/rowspan}> - Number of rows that the cell is to span
<{tablecells/headers}> - The headers for this cell
<{th/scope}> - Specifies which cells the header cell applies to
<{th/abbr}> - Alternative label to use for the header cell when referencing the cell in other contexts
[=Allowed ARIA role attribute values=]:
columnheader, rowheader role (each are default - do not set) or Any other role value.
[=Allowed ARIA state and property attributes=]:
Global aria-* attributes
Any aria-* attributes applicable to the default or allowed roles.
DOM interface:
        interface HTMLTableHeaderCellElement : HTMLTableCellElement {
          attribute DOMString scope;
          attribute DOMString abbr;
        };
The <{th}> element represents a header cell in a table. The <{th}> element may have a scope content attribute specified. The scope attribute is an enumerated attribute with five states, four of which have explicit keywords:
The row keyword, which maps to the row state
The row state means the header cell applies to some of the subsequent cells in the same row(s).
The col keyword, which maps to the column state
The column state means the header cell applies to some of the subsequent cells in the same column(s).
The rowgroup keyword, which maps to the row group state
The row group state means the header cell applies to all the remaining cells in the row group. A <{th}> element's scope attribute must not be in the row group state if the element is not anchored in a row group.
The colgroup keyword, which maps to the column group state
The colgroup group state means the header cell applies to all the remaining cells in the column group. A <{th}> element's scope attribute must not be in the column group state if the element is not anchored in a column group.
The auto state
The auto state makes the header cell apply to a set of cells selected based on context.
The scope attribute's missing value default is the auto state. The <{th}> element may have an abbr content attribute specified. Its value must be an alternative label for the header cell, to be used when referencing the cell in other contexts (e.g., when describing the header cells that apply to a data cell). It is typically an abbreviated form of the full header cell, but can also be an expansion, or merely a different phrasing.
The following snippet shows how an author could use the <{th/abbr}> attribute to provide abbreviated or expanded forms of different header cells. <table> <caption> Fruits of the world </caption> <thead> <tr> <th abbr="Fruit"> Common Fruit Name </th> <th abbr="Scientific Name"> Scientific Fruit Name </th> <th abbr="Canada"> CA </th> <th abbr="Latin America"> LATAM </th> <th abbr="Southeast Asia"> SEA </th> <!-- ... --> </tr> </thead> <!-- ... --> </table>
The <{th}> element and its colspan, rowspan, headers, and scope attributes take part in the table model. The scope IDL attribute must reflect the content attribute of the same name, limited to only known values. The abbr IDL attribute must reflect the content attribute of the same name.
The following example shows how the scope attribute's rowgroup value affects which data cells a header cell applies to. Here is a markup fragment showing a table:

The <{tbody}> elements in this example identify the range of the row groups.

<table> <caption>Measurement of legs and tails in Cats and English speakers</caption> <thead> <tr> <th> ID </th> <th> Measurement </th> <th> Average </th> <th> Maximum </th> </tr> </thead> <tbody> <tr> <td> </td> <th scope="rowgroup"> Cats </th> <td> </td> <td> </td> </tr> <tr> <td> 93 </td> <th scope="row"> Legs </th> <td> 3.5 </td> <td> 4 </td> </tr> <tr> <td> 10 </td> <th scope="row"> Tails </th> <td> 1 </td> <td> 1 </td> </tr> </tbody> <tbody> <tr> <td> </td> <th scope="rowgroup"> English speakers </th> <td> </td> <td> </td> </tr> <tr> <td> 32 </td> <th scope="row"> Legs </th> <td> 2.67 </td> <td> 4 </td> </tr> <tr> <td> 35 </td> <th scope="row"> Tails </th> <td> 0.33 </td> <td> 1 </td> </tr> </tbody> </table> This would result in the following table:
Measurement of legs and tails in Cats and English speakers
ID Measurement Average Maximum
Cats
93 Legs 3.5 4
10 Tails 1 1
English speakers
32 Legs 2.67 4
35 Tails 0.33 1
The header cells in row 1 ("ID", "Measurement", "Average" and "Maximum") each apply only to the cells in their column. The header cells with a scope="rowgroup" ("Cats" and 'English speakers') apply to all the cells in their row group other than the cells (to their left) in column 1: The header "Cats" (row 2, column 2) applies to the headers "Legs" (row 3, column 2) and "Tails" (row 4, column 2) and to the data cells in rows 2, 3 and 4 of the "Average" and "Maximum" columns. The header 'English speakers' (row 5, column 2) applies to the headers "Legs" (row 6, column 2) and "Tails" (row 7, column 2) and to the data cells in rows 5, 6 and 7 of the "Average" and "Maximum" columns. Each of the "Legs" and "Tails" header cells has a scope="row" and therefore apply to the data cells (to the right) in their row, from the "Average" and "Maximum" columns. Representation of the example table overlaid with arrows indicating which cells each header applies to.

Attributes common to td and <{th}> elements

The <{td}> and <{th}> elements may have a colspan content attribute specified, whose value must be a valid non-negative integer greater than zero. The <{td}> and <{th}> elements may also have a rowspan content attribute specified, whose value must be a valid non-negative integer. For this attribute, the value zero means that the cell is to span all the remaining rows in the row group. These attributes give the number of columns and rows respectively that the cell is to span. These attributes must not be used to overlap cells, as described in the table model.
The <{td}> and <{th}> element may have a headers content attribute specified. The headers attribute, if specified, must contain a string consisting of an unordered set of unique space-separated tokens that are case-sensitive, each of which must have the value of an <{global/id}> of a <{th}> element taking part in the same table as the <{td}> or <{th}> element (as defined by the table model). A <{th}> element with <{global/id}> id is said to be directly targeted by all td and <{th}> elements in the same table that have headers attributes whose values include as one of their tokens the ID id. A <{th}> element A is said to be targeted by a th or <{td}> element B if either A is directly targeted by B or if there exists an element C that is itself targeted by the element B and A is directly targeted by C. A <{th}> element must not be targeted by itself. The colspan, rowspan, and headers attributes take part in the table model.
The td and <{th}> elements implement interfaces that inherit from the HTMLTableCellElement interface: 
    interface HTMLTableCellElement : HTMLElement {
      attribute unsigned long colSpan;
      attribute unsigned long rowSpan;
      [SameObject, PutForwards=value] readonly attribute DOMTokenList headers;
      readonly attribute long cellIndex;
    };
cell . cellIndex
Returns the position of the cell in the row's cells list. This does not necessarily correspond to the x-position of the cell in the table, since earlier cells might cover multiple rows or columns. Returns -1 if the element isn't in a row.
The colSpan IDL attribute must reflect the colspan content attribute. Its default value is 1. The rowSpan IDL attribute must reflect the rowspan content attribute. Its default value is 1. The headers IDL attribute must reflect the content attribute of the same name. The cellIndex IDL attribute must, if the element has a parent <{tr}> element, return the index of the cell's element in the parent element's cells collection. If there is no such parent element, then the attribute must return -1.

Processing model

The various table elements and their content attributes together define the table model. A table consists of cells aligned on a two-dimensional grid of slots with coordinates (x, y). The grid is finite, and is either empty or has one or more slots. If the grid has one or more slots, then the x coordinates are always in the range 0 ≤ x < xwidth, and the y coordinates are always in the range 0 ≤ y < yheight. If one or both of xwidth and yheight are zero, then the table is empty (has no slots). Tables correspond to <{table}> elements. A cell is a set of slots anchored at a slot (cellx, celly), and with a particular width and height such that the cell covers all the slots with coordinates (x, y) where cellx ≤ x < cellx+width and celly ≤ y < celly+height. Cells can either be data cells or header cells. Data cells correspond to <{td}> elements, and header cells correspond to <{th}> elements. Cells of both types can have zero or more associated header cells. It is possible, in certain error cases, for two cells to occupy the same slot. A row is a complete set of slots from x=0 to x=xwidth-1, for a particular value of y. Rows usually correspond to <{tr}> elements, though a row group can have some implied rows at the end in some cases involving cells spanning multiple rows. A column is a complete set of slots from y=0 to y=yheight-1, for a particular value of x. Columns can correspond to <{col}> elements. In the absence of <{col}> elements, columns are implied. A row group is a set of rows anchored at a slot (0, groupy) with a particular height such that the row group covers all the slots with coordinates (x, y) where 0 ≤ x < xwidth and groupy ≤ y < groupy+height. Row groups correspond to <{tbody}>, <{thead}>, and <{tfoot}> elements. Not every row is necessarily in a row group. A column group is a set of columns anchored at a slot (groupx, 0) with a particular width such that the column group covers all the slots with coordinates (x, y) where groupx ≤ x < groupx+width and 0 ≤ y < yheight. Column groups correspond to <{colgroup}> elements. Not every column is necessarily in a column group. Row groups cannot overlap each other. Similarly, column groups cannot overlap each other. A cell cannot cover slots that are from two or more row groups. However, it is possible for a cell to be in multiple column groups. All the slots that form part of one cell are part of zero or one row groups and zero or more column groups. In addition to cells, columns, rows, row groups, and column groups, tables can have a <{caption}> element associated with them. This gives the table a heading, or legend. A table model error is an error with the data represented by table elements and their descendants. Documents must not have table model errors.
Forming a table
User agents must use the following algorithm to determine