Chapter 17: Header Groups Guide

Core Idea

A "header group" is just one row of headers — most tables have exactly one, but nested/grouped columns produce multiple header rows (multiple header groups), one per depth level.

Key Concepts

• Get header groups: table.getHeaderGroups() (most common); with column pinning enabled, use table.get[Start/Center/End]HeaderGroups() for the pinned/center subsets.
• A header group object has exactly three properties: id (derived from depth, stable React key), depth (zero-indexed header row index), headers (the array of Header objects in that row).
• Render by mapping headerGroup.headers, giving each <th> a colSpan={header.colSpan}.

Code Examples

<thead>
  {table.getHeaderGroups().map((headerGroup) => (
    <tr key={headerGroup.id}>
      {headerGroup.headers.map((header) => (
        <th key={header.id} colSpan={header.colSpan}>{/* ... */}</th>
      ))}
    </tr>
  ))}
</thead>

• What it demonstrates: the standard two-level map (header groups → headers) every <thead> in this library follows, regardless of how many header rows exist.

Key Takeaways

1. A single-row <thead> and a multi-row grouped <thead> use the exact same rendering code — table.getHeaderGroups() just returns one entry vs. several.
2. Always apply header.colSpan on the <th>, even for single-row tables — grouped columns depend on it, and it's a no-op (1) otherwise.

Connects To

• Headers Guide: the Header objects inside headerGroup.headers, including rowSpan for uneven column trees.
• Column Definitions Guide: columnHelper.group(...) is what produces multiple header groups.