HTML table element

Reference for the HTML table element and its sections: caption, thead, tbody, tr, th, and td, including scope and headers. Tables are for tabular data, not layout.

The table element represents tabular data — data that belongs in rows and columns. It is not a tool for visual page layout; CSS handles layout. This one page deepens the catalog cards for table, thead, tbody, tr, th, and td, and it covers caption, which the short catalog does not list as its own card. There are no separate thin pages for those child elements.

A common, robust order is: an optional caption, optional colgroup elements, an optional thead, one or more tbody sections (or rows), and an optional tfoot. Multiple tbody elements are allowed. thead, tbody, and tfoot each contain tr rows. Header cells are th; data cells are td.

Examples are complete tables checked as a parse tree. Screen-reader table navigation, visual rendering, and CSS layout were not tested in a browser.

Official sources: MDN <table> element and the WHATWG HTML Living Standard. Fragments were checked with Python 3.13 html.parser. That parser builds an element tree; it is not a WHATWG conformance checker, and this is not a browser or accessibility test.

HTML tag catalog → · HTML tutorial overview →

Tabular data, not layout

Use table when the meaning of a cell depends on its column and row headings: schedules, comparisons, numeric reports. Do not use a table to position a sidebar, a two-column article, or a form layout. Those cases belong to CSS (and to semantic elements such as header, nav, and main).

caption

The caption element, if present, must be the first child of the table. It is the table's title. A visible caption helps everyone identify the data set; it is not a substitute for a page heading, and a page heading is not a substitute for a caption when the table needs its own name.

thead

thead groups the header row or rows at the top of the table, typically column labels in th cells. A table may have at most one thead. Keep header cells in thead when they describe columns for the following bodies.

tbody

tbody groups data rows. A table may have several tbody sections, for example to split groups of rows. If you write thead or tfoot, use explicit tbody as well rather than leaving body rows as loose tr children mixed with those sections.

tfoot, when used, contains summary rows. The current HTML Standard allows tfoot after the body sections. This page does not add a separate tfoot example in order to keep the demonstrated structure small.

tr, th, and td

tr represents a row. th is a header cell; td is a data cell. colspan and rowspan span cells. Do not use empty spacer cells as a layout mechanism.

scope, headers, and a complete table

scope on th tells the user agent which cells the header describes: col, row, colgroup, or rowgroup. For a simple two-way table, scope="col" on column headers and scope="row" on row headers is the usual pattern. The headers attribute on a cell lists the id values of th cells that apply, and is meant for more complex tables where scope is not enough.

scope and headers are for describing the data, not for styling. Visual bold or centering of th in a user agent stylesheet is incidental; the structural relationship is what matters.

caption, thead, tbody, and scope

<table>
  <caption>
  <thead><tr><th scope="col">
  <tbody><tr><th scope="row"><td>

A data table with a caption, column headers, and row headers. This is not a layout grid.

AttributeDescription
captionOptional first child. The title of the table.
scopeOn th: col, row, colgroup, or rowgroup. It identifies the header's direction, not a CSS class.
headersOn td or th, a space-separated list of th id values for complex associations. Not needed in this simple example.
colspan, rowspanPositive integers that span cells. Use them for merged data cells, not for empty layout scaffolding.
  • thead, tbody, th, and td are covered here rather than on separate synonym pages. Catalog cards still link to these sections.
html
<table>
  <caption>Weekly watering minutes by bed</caption>
  <thead>
    <tr>
      <th scope="col">Bed</th>
      <th scope="col">Monday</th>
      <th scope="col">Thursday</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row">Herbs</th>
      <td>10</td>
      <td>8</td>
    </tr>
    <tr>
      <th scope="row">Tomatoes</th>
      <td>20</td>
      <td>15</td>
    </tr>
  </tbody>
</table>

What this markup means

The caption names the data set. thead holds column headers with scope="col". Each body row starts with a th that has scope="row". The numeric cells are td data, not layout spacers.

Related: Tag catalog: <table>, Tag catalog: <thead>, Tag catalog: <tbody>, Tag catalog: <th>, Tag catalog: <td>

MDN documentation → · WHATWG HTML Standard →