Tables, your secret layout friend! Now with added lists.

This specification is an experimental breakup of the HTML specification. You can see the full list on the index page and take part in the discussion in the repository.

The table element

Categories:

Flow content.

Palpable content.

Contexts in which this element can be used:

Where flow content is expected.

Content model:

In this order: optionally a caption 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), optionally intermixed with one or more script-supporting elements.

Tag omission in text/html:

Neither tag is omissible.

Content attributes:

Global attributes

border

sortable — Enables a sorting interface for the table

Allowed ARIA role attribute values:

Any 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;
  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 = -1);
  void deleteRow(long index);
  attribute boolean sortable;
  void stopSorting();

  // also has obsolete members
           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 to provide such information is given below.

Tables should not be used as layout aids. Historically, some Web authors have misused tables in HTML as a way to control their page layout. This usage is non-conforming, because tools attempting to extract tabular data from such documents would obtain very confusing results. In particular, users of accessibility tools like screen readers are likely to find it very difficult to navigate pages with tables used for layout.

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

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 (non-conforming) 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:

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.

The sortable attribute is used in the table sorting model.

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

The stopSorting() method is used in the table sorting model.

The IDL attribute sortable must reflect the sortable content attribute.

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

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

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 descendant table elements.

Tag omission in text/html:

A caption element's end tag can be omitted if the caption element is not immediately followed by a space character or a comment.

Content attributes:

Global attributes

Allowed ARIA role attribute values:

Any role value.

Allowed ARIA State and Property Attributes:

Global aria-* attributes

Any aria-* attributes applicable to the allowed roles.

DOM interface:

interface HTMLTableCaptionElement : HTMLElement {
  // also has obsolete members
};

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.

A caption can introduce context for a table, making it significantly easier to understand.

<caption>
<p>Table 1.
<p>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>

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

Global aria-* attributes

DOM interface:

interface HTMLTableColElement : HTMLElement {
  attribute unsigned long span;

  // also has obsolete members
};

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 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 — Number of columns spanned by the element

Allowed ARIA role attribute values:

None

Allowed ARIA State and Property Attributes:

Global aria-* attributes

DOM interface:

HTMLTableColElement, same as for colgroup elements. This interface defines one member, 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 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 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 can 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 can 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:

Any role value.

Allowed ARIA State and Property Attributes:

Global aria-* attributes

Any aria-* attributes applicable to the allowed roles.

DOM interface:

interface HTMLTableSectionElement : HTMLElement {
  readonly attribute HTMLCollection rows;
  HTMLElement insertRow(optional long index = -1);
  void deleteRow(long index);

  // also has obsolete members
};

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.

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 remove the indexth element in the rows collection from its parent. 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.

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 can be omitted if the thead element is immediately followed by a tbody or tfoot element.

Content attributes:

Global attributes

Allowed ARIA role attribute values:

Any role value.

Allowed ARIA State and Property Attributes:

Global aria-* attributes

Any aria-* attributes applicable to the 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.

<table>
 <caption> School auction sign-up sheet </caption>
 <thead>
  <tr>
   <th><label for=e1>Name</label>
   <th><label for=e2>Product</label>
   <th><label for=e3>Picture</label>
   <th><label for=e4>Price</label>
  <tr>
   <td>Your name here
   <td>What are you selling?
   <td>Link to a picture
   <td>Your reserve price
 <tbody>
  <tr>
   <td>Ms Danus
   <td>Doughnuts
   <td><img src="http://example.com/mydoughnuts.png" title="Doughnuts from Ms Danus">
   <td>$45
  <tr>
   <td><input id=e1 type=text name=who required form=f>
   <td><input id=e2 type=text name=what required form=f>
   <td><input id=e3 type=url name=pic form=f>
   <td><input id=e4 type=number step=0.01 min=0 value=0 required form=f>
</table>
<form id=f action="/auction.cgi">
 <input type=button name=add value="Submit">
</form>

The tfoot 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 and before any tbody and tr elements, but only if there are no other tfoot elements that are children of the table element.

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 can be omitted if the tfoot element is immediately followed by a tbody element, or if there is no more content in the parent element.

Content attributes:

Global attributes

Allowed ARIA role attribute values:

Any role value.

Allowed ARIA State and Property Attributes:

Global aria-* attributes

Any aria-* attributes applicable to the 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 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 can 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:

Any role value.

Allowed ARIA State and Property Attributes:

Global aria-* attributes

Any aria-* attributes applicable to the allowed roles.

DOM interface:

interface HTMLTableRowElement : HTMLElement {
  readonly attribute long rowIndex;
  readonly attribute long sectionRowIndex;
  readonly attribute HTMLCollection cells;
  HTMLElement insertCell(optional long index = -1);
  void deleteCell(long index);

  // also has obsolete members
};

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 remove the indexth element in the cells collection from its parent. If index is less than zero or greater than or equal to the number of elements in the cells collection, the method must instead throw an IndexSizeError exception.

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.

Tag omission in text/html:

A td element's end tag can be omitted if the td 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

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:

Any role value.

Allowed ARIA State and Property Attributes:

Global aria-* attributes

Any aria-* attributes applicable to the allowed roles.

DOM interface:

interface HTMLTableDataCellElement : HTMLTableCellElement {
  // also has obsolete members
};

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 non-visual environments or where displaying the table as a 2D grid is impractical, may give the user context for the cell when rendering the contents of a cell; for instance, giving its position in the table model, or listing the cell's header cells (as determined by the algorithm for assigning header cells). When a cell's header cells are being listed, user agents may use the value of abbr attributes on those header cells, if any, instead of the contents of the header cells themselves.

<table>
 <tr>
  <th><input value="Name">
  <th><input value="Paid ($)">
 <tr>
  <td><input value="Jeff">
  <td><input value="14">
 <tr>
  <td><input value="Britta">
  <td><input value="9">
 <tr>
  <td><input value="Abed">
  <td><input value="25">
 <tr>
  <td><input value="Shirley">
  <td><input value="2">
 <tr>
  <td><input value="Annie">
  <td><input value="5">
 <tr>
  <td><input value="Troy">
  <td><input value="5">
 <tr>
  <td><input value="Pierce">
  <td><input value="1000">
 <tr>
  <th><input value="Total">
  <td><output value="1060">
</table>

The th element

Categories:

If the th element is a sorting interface th element: Interactive content.

Otherwise: 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, sectioning content, or heading content descendants, and if the th element is a sorting interface th element, no interactive content descendants.

Tag omission in text/html:

A th element's end tag can 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

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

scope — Specifies which cells the header cell applies to

abbr — Alternative label to use for the header cell when referencing the cell in other contexts

sorted — Column sort direction and ordinality

Allowed ARIA role attribute values:

Any role value.

Allowed ARIA State and Property Attributes:

Global aria-* attributes

Any aria-* attributes applicable to the allowed roles.

DOM interface:

interface HTMLTableHeaderCellElement : HTMLTableCellElement {
  attribute DOMString scope;
  attribute DOMString abbr;
  attribute DOMString sorted;
  void sort();
};

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 column 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 sorted attribute is used in the table sorting model.

The th element and its colspan, rowspan, headers, and scope attributes take part in the table model.

The sort() method is used in the table sorting model.

The scope IDL attribute must reflect the content attribute of the same name, limited to only known values.

The abbr and sorted IDL attributes must reflect the content attributes 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:

<table>
 <thead>
  <tr> <th> ID <th> Measurement <th> Average <th> Maximum
 <tbody>
  <tr> <td> <th scope=rowgroup> Cats <td> <td>
  <tr> <td> 93 <th scope=row> Legs <td> 3.5 <td> 4
  <tr> <td> 10 <th scope=row> Tails <td> 1 <td> 1
 <tbody>
  <tr> <td> <th scope=rowgroup> English speakers <td> <td>
  <tr> <td> 32 <th scope=row> Legs <td> 2.67 <td> 4
  <tr> <td> 35 <th scope=row> Tails <td> 0.33 <td> 1
</table>

This would result in the following table:

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 headers in the first row all apply directly down to the rows in their column.

The headers with the explicit scope attributes apply to all the cells in their row group other than the cells in the first column.

The remaining headers apply just to the cells to the right of them.

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 description of 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 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 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;
  [PutForwards=value] readonly attribute DOMSettableTokenList headers;
  readonly attribute long cellIndex;

  // also has obsolete members
};

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 < x_width, and the y coordinates are always in the range 0 ≤ y < y_height. If one or both of x_width and y_height 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 (cell_x, cell_y), and with a particular width and height such that the cell covers all the slots with coordinates (x, y) where cell_x ≤ x < cell_x+width and cell_y ≤ y < cell_y+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=x_width-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=y_height-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, group_y) with a particular height such that the row group covers all the slots with coordinates (x, y) where 0 ≤ x < x_width and group_y ≤ y < group_y+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 (group_x, 0) with a particular width such that the column group covers all the slots with coordinates (x, y) where group_x ≤ x < group_x+width and 0 ≤ y < y_height. 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. It is, however, 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.

The ul element

Categories:

Flow content.

If the element's children include at least one li element: Palpable content.

Contexts in which this element can be used:

Where flow content is expected.

Content model:

Zero or more li and script-supporting elements.

Tag omission in text/html:

Neither tag is omissible.

Content attributes:

Global attributes

Allowed ARIA role attribute values:

list role (default - do not set), directory, group, listbox, menu, menubar, presentation,radiogroup, tablist, toolbar or tree.

Allowed ARIA State and Property Attributes:

Global aria-* attributes

Any aria-* attributes applicable to the allowed roles.

DOM interface:

interface HTMLUListElement : HTMLElement {
  // also has obsolete members
};

The ul element represents a list of items, where the order of the items is not important — that is, where changing the order would not materially change the meaning of the document.

The items of the list are the li element child nodes of the ul element.

<p>I have lived in the following countries:</p>
<ul>
 <li>Norway
 <li>Switzerland
 <li>United Kingdom
 <li>United States
</ul>

<p>I have lived in the following countries:</p>
<ul>
 <li>Switzerland
 <li>Norway
 <li>United Kingdom
 <li>United States
</ul>

The ol element

Categories:

Flow content.

If the element's children include at least one li element: Palpable content.

Contexts in which this element can be used:

Where flow content is expected.

Content model:

Zero or more li and script-supporting elements.

Tag omission in text/html:

Neither tag is omissible.

Content attributes:

Global attributes

reversed — Number the list backwards

start — Ordinal value of the first item

type — Kind of list marker

Allowed ARIA role attribute values:

list role (default - do not set), directory, group, listbox, menu, menubar, presentation, radiogroup, tablist, toolbar or tree.

Allowed ARIA State and Property Attributes:

Global aria-* attributes

Any aria-* attributes applicable to the allowed roles.

DOM interface:

interface HTMLOListElement : HTMLElement {
  attribute boolean reversed;
  attribute long start;
  attribute DOMString type;

  // also has obsolete members
};

The ol element represents a list of items, where the items have been intentionally ordered, such that changing the order would change the meaning of the document.

The items of the list are the li element child nodes of the ol element, in tree order.

The reversed attribute is a boolean attribute. If present, it indicates that the list is a descending list (..., 3, 2, 1). If the attribute is omitted, the list is an ascending list (1, 2, 3, ...).

The start attribute, if present, must be a valid integer giving the ordinal value of the first list item.

If the start attribute is present, user agents must parse it as an integer, in order to determine the attribute's value. The default value, used if the attribute is missing or if the value cannot be converted to a number according to the referenced algorithm, is 1 if the element has no reversed attribute, and is the number of child li elements otherwise.

The first item in the list has the ordinal value given by the ol element's start attribute, unless that li element has a value attribute with a value that can be successfully parsed, in which case it has the ordinal value given by that value attribute.

Each subsequent item in the list has the ordinal value given by its value attribute, if it has one, or, if it doesn't, the ordinal value of the previous item, plus one if the reversed is absent, or minus one if it is present.

The type attribute can be used to specify the kind of marker to use in the list, in the cases where that matters (e.g. because items are to be referenced by their number/letter). The attribute, if specified, must have a value that is a case-sensitive match for one of the characters given in the first cell of one of the rows of the following table. The type attribute represents the state given in the cell in the second column of the row whose first cell matches the attribute's value; if none of the cells match, or if the attribute is omitted, then the attribute represents the decimal state.

User agents should render the items of the list in a manner consistent with the state of the type attribute of the ol element. Numbers less than or equal to zero should always use the decimal system regardless of the type attribute.

For CSS user agents, a mapping for this attribute to the 'list-style-type' CSS property is given in the rendering section (the mapping is straightforward: the states above have the same names as their corresponding CSS values).

It is possible to redefine the default CSS list styles used to implement this attribute in CSS user agents; doing so will affect how list items are rendered.

The reversed, start, and type IDL attributes must reflect the respective content attributes of the same name. The start IDL attribute has the same default as its content attribute.

<p>I have lived in the following countries (given in the order of when
I first lived there):</p>
<ol>
 <li>Switzerland
 <li>United Kingdom
 <li>United States
 <li>Norway
</ol>

<p>I have lived in the following countries (given in the order of when
I first lived there):</p>
<ol>
 <li>United Kingdom
 <li>Switzerland
 <li>United States
 <li>Norway
</ol>

The li element

Categories:

None.

Contexts in which this element can be used:

Inside ol elements.

Inside ul elements.

Inside menu elements whose type attribute is in the toolbar state.

Content model:

Flow content.

Tag omission in text/html:

An li element's end tag can be omitted if the li element is immediately followed by another li element or if there is no more content in the parent element.

Content attributes:

Global attributes

If the element is a child of an ol element: value — Ordinal value of the list item

Allowed ARIA role attribute values:

listitem role (default - do not set), menuitem, menuitemcheckbox, menuitemradio, option, radio, tab, treeitem or presentation.

Allowed ARIA State and Property Attributes:

Global aria-* attributes

Any aria-* attributes applicable to the allowed roles.

DOM interface:

interface HTMLLIElement : HTMLElement {
  attribute long value;

  // also has obsolete members
};

The li element represents a list item. If its parent element is an ol, ul, or menu element, then the element is an item of the parent element's list, as defined for those elements. Otherwise, the list item has no defined list-related relationship to any other li element.

If the parent element is an ol element, then the li element has an ordinal value.

The value attribute, if present, must be a valid integer giving the ordinal value of the list item.

If the value attribute is present, user agents must parse it as an integer, in order to determine the attribute's value. If the attribute's value cannot be converted to a number, the attribute must be treated as if it was absent. The attribute has no default value.

The value attribute is processed relative to the element's parent ol element (q.v.), if there is one. If there is not, the attribute has no effect.

The value IDL attribute must reflect the value of the value content attribute.

<figure>
 <figcaption>The top 10 movies of all time</figcaption>
 <ol>
  <li value="10"><cite>Josie and the Pussycats</cite>, 2001</li>
  <li value="9"><cite lang="sh">Црна мачка, бели мачор</cite>, 1998</li>
  <li value="8"><cite>A Bug's Life</cite>, 1998</li>
  <li value="7"><cite>Toy Story</cite>, 1995</li>
  <li value="6"><cite>Monsters, Inc</cite>, 2001</li>
  <li value="5"><cite>Cars</cite>, 2006</li>
  <li value="4"><cite>Toy Story 2</cite>, 1999</li>
  <li value="3"><cite>Finding Nemo</cite>, 2003</li>
  <li value="2"><cite>The Incredibles</cite>, 2004</li>
  <li value="1"><cite>Ratatouille</cite>, 2007</li>
 </ol>
</figure>

<figure>
 <figcaption>The top 10 movies of all time</figcaption>
 <ol reversed>
  <li><cite>Josie and the Pussycats</cite>, 2001</li>
  <li><cite lang="sh">Црна мачка, бели мачор</cite>, 1998</li>
  <li><cite>A Bug's Life</cite>, 1998</li>
  <li><cite>Toy Story</cite>, 1995</li>
  <li><cite>Monsters, Inc</cite>, 2001</li>
  <li><cite>Cars</cite>, 2006</li>
  <li><cite>Toy Story 2</cite>, 1999</li>
  <li><cite>Finding Nemo</cite>, 2003</li>
  <li><cite>The Incredibles</cite>, 2004</li>
  <li><cite>Ratatouille</cite>, 2007</li>
 </ol>
</figure>

While it is conforming to include heading elements (e.g. h1) inside li elements, it likely does not convey the semantics that the author intended. A heading starts a new section, so a heading in a list implicitly splits the list into spanning multiple sections.

The dl element

Categories:

Flow content.

If the element's children include at least one name-value group: Palpable content.

Contexts in which this element can be used:

Where flow content is expected.

Content model:

Zero or more groups each consisting of one or more dt elements followed by one or more dd elements, optionally intermixed with script-supporting elements.

Tag omission in text/html:

Neither tag is omissible.

Content attributes:

Global attributes

Allowed ARIA role attribute values:

Any role value.

Allowed ARIA State and Property Attributes:

Global aria-* attributes

Any aria-* attributes applicable to the allowed roles.

DOM interface:

interface HTMLDListElement : HTMLElement {
  // also has obsolete members
};

The dl element represents an association list consisting of zero or more name-value groups (a description list). A name-value group consists of one or more names (dt elements) followed by one or more values (dd elements), ignoring any nodes other than dt and dd elements. Within a single dl element, there should not be more than one dt element for each name.

Name-value groups may be terms and definitions, metadata topics and values, questions and answers, or any other groups of name-value data.

The values within a group are alternatives; multiple paragraphs forming part of the same value must all be given within the same dd element.

The order of the list of groups, and of the names and values within each group, may be significant.

If a dl element has no dt or dd element children, it contains no groups.

If a dl element has one or more non-whitespace Text node children, or has child elements that are neither dt nor dd elements, all such Text nodes and elements, as well as their descendants (including any dt or dd elements), do not form part of any groups in that dl.

If a dl element has one or more dt element children but no dd element children, then it consists of one group with names but no values.

If a dl element has one or more dd element children but no dt element children, then it consists of one group with values but no names.

If a dl element's first dt or dd element child is a dd element, then the first group has no associated name.

If a dl element's last dt or dd element child is a dt element, then the last group has no associated value.

When a dl element doesn't match its content model, it is often due to accidentally using dd elements in the place of dt elements and vice versa. Conformance checkers can spot such mistakes and might be able to advise authors how to correctly use the markup.

<dl>
 <dt> Authors
 <dd> John
 <dd> Luke
 <dt> Editor
 <dd> Frank
</dl>

<dl>
 <dt lang="en-US"> <dfn>color</dfn> </dt>
 <dt lang="en-GB"> <dfn>colour</dfn> </dt>
 <dd> A sensation which (in humans) derives from the ability of
 the fine structure of the eye to distinguish three differently
 filtered analyses of a view. </dd>
</dl>

<dl>
 <dt> Last modified time </dt>
 <dd> 2004-12-23T23:33Z </dd>
 <dt> Recommended update interval </dt>
 <dd> 60s </dd>
 <dt> Authors </dt>
 <dt> Editors </dt>
 <dd> Robert Rothman </dd>
 <dd> Daniel Jackson </dd>
</dl>

<p>Determine the victory points as follows (use the
first matching case):</p>
<dl>
 <dt> If you have exactly five gold coins </dt>
 <dd> You get five victory points </dd>
 <dt> If you have one or more gold coins, and you have one or more silver coins </dt>
 <dd> You get two victory points </dd>
 <dt> If you have one or more silver coins </dt>
 <dd> You get one victory point </dd>
 <dt> Otherwise </dt>
 <dd> You get no victory points </dd>
</dl>

<dl>
 <dt><dfn>Apartment</dfn>, n.</dt>
 <dd>An execution context grouping one or more threads with one or
 more COM objects.</dd>
 <dt><dfn>Flat</dfn>, n.</dt>
 <dd>A deflated tire.</dd>
 <dt><dfn>Home</dfn>, n.</dt>
 <dd>The user's login directory.</dd>
</dl>

The dl element is inappropriate for marking up dialogue. Examples of how to mark up dialogue are shown below.

The dt element

Categories:

None.

Contexts in which this element can be used:

Before dd or dt elements inside dl elements.

Content model:

Flow content, but with no header, footer, sectioning content, or heading content descendants.

Tag omission in text/html:

A dt element's end tag can be omitted if the dt element is immediately followed by another dt element or a dd element.

Content attributes:

Global attributes

Allowed ARIA role attribute values:

Any role value.

Allowed ARIA State and Property Attributes:

Global aria-* attributes

Any aria-* attributes applicable to the allowed roles.

DOM interface:

Uses HTMLElement.

The dt element represents the term, or name, part of a term-description group in a description list (dl element).

The dt element itself, when used in a dl element, does not indicate that its contents are a term being defined, but this can be indicated using the dfn element.

<article>
 <h1>FAQ</h1>
 <dl>
  <dt>What do we want?</dt>
  <dd>Our data.</dd>
  <dt>When do we want it?</dt>
  <dd>Now.</dd>
  <dt>Where is it?</dt>
  <dd>We are not sure.</dd>
 </dl>
</article>

The dd element

Categories:

None.

Contexts in which this element can be used:

After dt or dd elements inside dl elements.

Content model:

Flow content.

Tag omission in text/html:

A dd element's end tag can be omitted if the dd element is immediately followed by another dd element or a dt element, or if there is no more content in the parent element.

Content attributes:

Global attributes

Allowed ARIA role attribute values:

Any role value.

Allowed ARIA State and Property Attributes:

Global aria-* attributes

Any aria-* attributes applicable to the allowed roles.

DOM interface:

Uses HTMLElement.

The dd element represents the description, definition, or value, part of a term-description group in a description list (dl element).

<dl>
 <dt><dfn>happiness</dfn></dt>
 <dd class="pronunciation">/'hæ p. nes/</dd>
 <dd class="part-of-speech"><i><abbr>n.</abbr></i></dd>
 <dd>The state of being happy.</dd>
 <dd>Good fortune; success. <q>Oh <b>happiness</b>! It worked!</q></dd>
 <dt><dfn>rejoice</dfn></dt>
 <dd class="pronunciation">/ri jois'/</dd>
 <dd><i class="part-of-speech"><abbr>v.intr.</abbr></i> To be delighted oneself.</dd>
 <dd><i class="part-of-speech"><abbr>v.tr.</abbr></i> To cause one to be delighted.</dd>
</dl>