HTML headers Attribute

What You’ll Learn

The headers attribute links table data cells to their header cells using space-separated id values. Screen readers use these associations to announce which row and column headers apply to each cell—especially important in complex tables with merged cells or multi-level headers.

Purpose of headers Attribute

The headers attribute is used on <td> and <th> elements to explicitly associate a cell with one or more header cells. Each referenced header must have a unique id attribute. This helps assistive technologies understand the relationship between data and the labels that describe it.

In simple tables with a single row of column headers and a single column of row headers, the scope attribute on <th> is often sufficient. The headers attribute becomes essential when scope alone cannot express the relationships—for example, when headers span multiple rows or columns with rowspan and colspan.

📝 Syntax

Add headers to a <td> or <th> with a space-separated list of header cell id values:

<table>
  <thead>
    <tr>
      <th id="name" scope="col">Name</th>
      <th id="score" scope="col">Score</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td headers="name">Alice</td>
      <td headers="score">92</td>
    </tr>
  </tbody>
</table>

Syntax Rules

• Valid on <td> and <th> elements inside a table.
• Value is a space-separated list of id values from header cells (<th>).
• Each referenced id must be unique within the document.
• A cell may reference multiple headers when it belongs to more than one row or column label.
• For simple tables, scope on <th> is often enough; use headers when relationships are ambiguous.

💎 Values

The headers attribute accepts one or more header cell id values, separated by spaces:

• headers="name" — Associates the cell with a single column or row header.
• headers="north q1 q1-sales" — Associates a cell with multiple headers: a row header, a group header, and a sub-header.
• headers="region q2-units" — Common in sales or financial tables with nested column groups.

<!-- Single header reference -->
<td headers="product">Widget A</td>

<!-- Multiple header references -->
<td headers="west q3 q3-revenue">$48,200</td>

Applicable Elements

scope vs headers

Examples Gallery

Basic header association, a multi-level sales table with rowspan and colspan, and dynamic headers with JavaScript.

<table>
  <caption>Student Scores</caption>
  <thead>
    <tr>
      <th id="name" scope="col">Name</th>
      <th id="score" scope="col">Score</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td headers="name">Alice</td>
      <td headers="score">92</td>
    </tr>
    <tr>
      <td headers="name">Bob</td>
      <td headers="score">87</td>
    </tr>
  </tbody>
</table>

<table>
  <caption>Quarterly Sales by Region</caption>
  <thead>
    <tr>
      <th id="region" rowspan="2">Region</th>
      <th id="q1" colspan="2">Q1</th>
      <th id="q2" colspan="2">Q2</th>
    </tr>
    <tr>
      <th id="q1-sales" headers="q1">Sales</th>
      <th id="q1-units" headers="q1">Units</th>
      <th id="q2-sales" headers="q2">Sales</th>
      <th id="q2-units" headers="q2">Units</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th id="north" scope="row">North</th>
      <td headers="north q1 q1-sales">$12,400</td>
      <td headers="north q1 q1-units">310</td>
      <td headers="north q2 q2-sales">$14,800</td>
      <td headers="north q2 q2-units">370</td>
    </tr>
    <tr>
      <th id="south" scope="row">South</th>
      <td headers="south q1 q1-sales">$9,600</td>
      <td headers="south q1 q1-units">240</td>
      <td headers="south q2 q2-sales">$11,200</td>
      <td headers="south q2 q2-units">280</td>
    </tr>
  </tbody>
</table>

<table>
  <tr>
    <th id="headerId">Revenue</th>
  </tr>
  <tr>
    <td id="dataCell">$5,000</td>
  </tr>
</table>

<script>
  var cell = document.getElementById("dataCell");
  cell.headers = "headerId";
  // or: cell.setAttribute("headers", "id1 id2");
</script>

♿ Accessibility

• Give every header a unique id — Referenced ids must exist and be unique within the page.
• Use headers for complex layouts — When rowspan, colspan, or nested headers break simple scope relationships.
• Add a <caption> — Summarize the table purpose before users navigate individual cells.
• Prefer semantic structure — Wrap headers in <thead> and data rows in <tbody>.
• Test with screen readers — Verify that NVDA, VoiceOver, or JAWS announce the correct header labels for each cell.
• Do not rely on visual position alone — Merged cells can confuse assistive tech without explicit headers references.

💡 Best Practices