This is revision 1.5612.
table
elementcaption
element,
followed by zero or more colgroup
elements, followed
optionally by a thead
element, followed optionally by
a tfoot
element, followed by either zero or more
tbody
elements or one or more tr
elements, followed optionally by a tfoot
element (but
there can only be one tfoot
element child in
total).border
interface HTMLTableElement : HTMLElement { attribute HTMLTableCaptionElement? caption; HTMLElement createCaption(); void deleteCaption(); attribute HTMLTableSectionElement? tHead; HTMLElement createTHead(); void deleteTHead(); attribute HTMLTableSectionElement? tFoot; HTMLElement createTFoot(); void deleteTFoot(); readonly attribute HTMLCollection tBodies; HTMLElement createTBody(); readonly attribute HTMLCollection rows; HTMLElement insertRow(optional long index); void deleteRow(long index); attribute DOMString border; };
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 provide such information is given below.
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.
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 to be used for layout 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.
The border
attribute may be specified on a table
element to
explicitly indicate that the table
element is not being
used for layout purposes. If specified, the attribute's value must
either be the empty string or the value "1
".
The attribute is used by certain user agents as an indication that
borders should be drawn around cells of the table.
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 layout 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 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.
caption
[ = value ]Returns the table's caption
element.
Can be set, to replace the caption
element. If the
new value is not a caption
element, throws a
HierarchyRequestError
exception.
createCaption
()Ensures the table has a caption
element, and returns it.
deleteCaption
()Ensures the table does not have a caption
element.
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.
createTHead
()Ensures the table has a thead
element, and returns it.
deleteTHead
()Ensures the table does not have a thead
element.
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.
createTFoot
()Ensures the table has a tfoot
element, and returns it.
deleteTFoot
()Ensures the table does not have a tfoot
element.
tBodies
Returns an HTMLCollection
of the tbody
elements of the table.
createTBody
()Creates a tbody
element, inserts it into the table, and returns it.
rows
Returns an HTMLCollection
of the tr
elements of the 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 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.
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, if the new value is a caption
element, the first caption
element child of the
table
element, if any, must be removed, and the new
value must be inserted as the first node of the table
element. If the new value is not a caption
element,
then a HierarchyRequestError
DOM exception must be
thrown instead.
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 a thead
element, the first thead
element child of the
table
element, if any, must be removed, and the new
value 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 not
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 a tfoot
element, the first tfoot
element child of the
table
element, if any, must be removed, and the new
value must be inserted immediately before the first element in the
table
element that is neither a caption
element, a colgroup
element, nor a thead
element, if any, or at the end of the table if there are no such
elements. If the new value is not 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 immediately
before the first element in the table
element that is
neither a caption
element, a colgroup
element, nor a thead
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 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 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:
rows
collection:IndexSizeError
exception.rows
collection has
zero elements in it, and the table
has no
tbody
elements in it: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.rows
collection has
zero elements in it:tr
element, append it to
the last tbody
element in the table, and return the
tr
element.rows
collection: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.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:
If index is equal to −1, then
index must be set to the number if items in the
rows
collection, minus
one.
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.
Otherwise, the method must remove the indexth element in the rows
collection from its parent.
The border
IDL
attribute must reflect the content attribute of the
same name.
Here is an example of a table being used to mark up a Sudoku puzzle. Observe the lack of headers, which are not necessary in such a table.
<section> <style scoped> table { border-collapse: collapse; border: solid thick; } colgroup, tbody { border: solid medium; } td { border: solid thin; height: 1.4em; width: 1.4em; text-align: center; padding: 0; } </style> <h1>Today's Sudoku</h1> <table> <colgroup><col><col><col> <colgroup><col><col><col> <colgroup><col><col><col> <tbody> <tr> <td> 1 <td> <td> 3 <td> 6 <td> <td> 4 <td> 7 <td> <td> 9 <tr> <td> <td> 2 <td> <td> <td> 9 <td> <td> <td> 1 <td> <tr> <td> 7 <td> <td> <td> <td> <td> <td> <td> <td> 6 <tbody> <tr> <td> 2 <td> <td> 4 <td> <td> 3 <td> <td> 9 <td> <td> 8 <tr> <td> <td> <td> <td> <td> <td> <td> <td> <td> <tr> <td> 5 <td> <td> <td> 9 <td> <td> 7 <td> <td> <td> 1 <tbody> <tr> <td> 6 <td> <td> <td> <td> 5 <td> <td> <td> <td> 2 <tr> <td> <td> <td> <td> <td> 7 <td> <td> <td> <td> <tr> <td> 9 <td> <td> <td> 8 <td> <td> 2 <td> <td> <td> 5 </table> </section>
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 use the table.
For instance, the following table:
Negative | Characteristic | Positive |
---|---|---|
Sad | Mood | Happy |
Failing | Grade | Passing |
...might 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:
<p>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> <caption>Characteristics with positive and negative sides</caption> <thead> <tr> <th id="n"> Negative <th> Characteristic <th> Positive <tbody> <tr> <td headers="n r1"> Sad <th id="r1"> Mood <td> Happy <tr> <td headers="n r2"> Failing <th id="r2"> Grade <td> Passing </table>
caption
<table> <caption> <strong>Characteristics with positive and negative sides.</strong> <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> </caption> <thead> <tr> <th id="n"> Negative <th> Characteristic <th> Positive <tbody> <tr> <td headers="n r1"> Sad <th id="r1"> Mood <td> Happy <tr> <td headers="n r2"> Failing <th id="r2"> Grade <td> Passing </table>
caption
, in a details
element<table> <caption> <strong>Characteristics with positive and negative sides.</strong> <details> <summary>Help</summary> <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> </details> </caption> <thead> <tr> <th id="n"> Negative <th> Characteristic <th> Positive <tbody> <tr> <td headers="n r1"> Sad <th id="r1"> Mood <td> Happy <tr> <td headers="n r2"> Failing <th id="r2"> Grade <td> Passing </table>
figure
<figure> <figcaption>Characteristics with positive and negative sides</figcaption> <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> <thead> <tr> <th id="n"> Negative <th> Characteristic <th> Positive <tbody> <tr> <td headers="n r1"> Sad <th id="r1"> Mood <td> Happy <tr> <td headers="n r2"> Failing <th id="r2"> Grade <td> Passing </table> </figure>
figure
's figcaption
<figure> <figcaption> <strong>Characteristics with positive and negative sides</strong> <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> </figcaption> <table> <thead> <tr> <th id="n"> Negative <th> Characteristic <th> Positive <tbody> <tr> <td headers="n r1"> Sad <th id="r1"> Mood <td> Happy <tr> <td headers="n r2"> Failing <th id="r2"> Grade <td> Passing </table> </figure>
Authors may also use other techniques, or combinations of the above techniques, as appropriate.
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> Negative <th> Positive <tbody> <tr> <th> Mood <td> Sad <td> Happy <tr> <th> Grade <td> Failing <td> Passing </table>
Good table layout 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.)
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.
Authors are encouraged to use CSS to achieve these effects.
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.