Table

Displays records in rows and columns.

When to use it

Records with several comparable fields: employees, cases, permits.

When not to use it

Layout. Use CSS grid.
A single record. Use a description list.

Examples

Each example is a conformance case: every emitter — React, and each framework adapter — is checked against exactly this markup.

basic

Rendered

Employees
Employee	ID	Department
Himanshu Dubey	EMP-001	Engineering
Meera Iyer	EMP-002	Product

HTML

<div class="gov-table-wrapper" tabindex="0" role="region" aria-label="Employees">
  <table class="gov-table">
    <caption class="gov-table__caption gov-visually-hidden">Employees</caption>
    <thead class="gov-table__head">
      <tr>
        <th scope="col" class="gov-table__header">Employee</th>
        <th scope="col" class="gov-table__header gov-table__header--numeric">ID</th>
        <th scope="col" class="gov-table__header">Department</th>
      </tr>
    </thead>
    <tbody class="gov-table__body">
      <tr class="gov-table__row">
        <td class="gov-table__cell">Himanshu Dubey</td>
        <td class="gov-table__cell gov-table__cell--numeric gov-tabular">EMP-001</td>
        <td class="gov-table__cell">Engineering</td>
      </tr>
      <tr class="gov-table__row">
        <td class="gov-table__cell">Meera Iyer</td>
        <td class="gov-table__cell gov-table__cell--numeric gov-tabular">EMP-002</td>
        <td class="gov-table__cell">Product</td>
      </tr>
    </tbody>
  </table>
</div>

{
  "caption": "Employees",
  "columns": [
    {
      "key": "name",
      "header": "Employee"
    },
    {
      "key": "id",
      "header": "ID",
      "numeric": true
    },
    {
      "key": "department",
      "header": "Department"
    }
  ],
  "rows": [
    {
      "name": "Himanshu Dubey",
      "id": "EMP-001",
      "department": "Engineering"
    },
    {
      "name": "Meera Iyer",
      "id": "EMP-002",
      "department": "Product"
    }
  ]
}

with-status

Rendered

Employees
Employee	Status
Himanshu Dubey	Active
Diksha Sharma	On leave

HTML

<div class="gov-table-wrapper" tabindex="0" role="region" aria-label="Employees">
  <table class="gov-table">
    <caption class="gov-table__caption gov-visually-hidden">Employees</caption>
    <thead class="gov-table__head">
      <tr>
        <th scope="col" class="gov-table__header">Employee</th>
        <th scope="col" class="gov-table__header">Status</th>
      </tr>
    </thead>
    <tbody class="gov-table__body">
      <tr class="gov-table__row">
        <td class="gov-table__cell">Himanshu Dubey</td>
        <td class="gov-table__cell">
          <span class="gov-status gov-status--success">Active</span>
        </td>
      </tr>
      <tr class="gov-table__row">
        <td class="gov-table__cell">Diksha Sharma</td>
        <td class="gov-table__cell">
          <span class="gov-status gov-status--warning">On leave</span>
        </td>
      </tr>
    </tbody>
  </table>
</div>

{
  "caption": "Employees",
  "columns": [
    {
      "key": "name",
      "header": "Employee"
    },
    {
      "key": "status",
      "header": "Status"
    }
  ],
  "rows": [
    {
      "name": "Himanshu Dubey",
      "status": {
        "component": "status-badge",
        "props": {
          "status": "success",
          "children": "Active"
        }
      }
    },
    {
      "name": "Diksha Sharma",
      "status": {
        "component": "status-badge",
        "props": {
          "status": "warning",
          "children": "On leave"
        }
      }
    }
  ]
}

sortable

Rendered

Employees
Employee	Department
Himanshu Dubey	Engineering

HTML

<div class="gov-table-wrapper" tabindex="0" role="region" aria-label="Employees">
  <table class="gov-table">
    <caption class="gov-table__caption gov-visually-hidden">Employees</caption>
    <thead class="gov-table__head">
      <tr>
        <th scope="col" class="gov-table__header" aria-sort="ascending">
          <a class="gov-table__sort" href="?sort=name&amp;dir=desc">Employee</a>
        </th>
        <th scope="col" class="gov-table__header" aria-sort="none">
          <a class="gov-table__sort" href="?sort=department">Department</a>
        </th>
      </tr>
    </thead>
    <tbody class="gov-table__body">
      <tr class="gov-table__row">
        <td class="gov-table__cell">Himanshu Dubey</td>
        <td class="gov-table__cell">Engineering</td>
      </tr>
    </tbody>
  </table>
</div>

{
  "caption": "Employees",
  "columns": [
    {
      "key": "name",
      "header": "Employee",
      "sort": "ascending",
      "sortHref": "?sort=name&dir=desc"
    },
    {
      "key": "department",
      "header": "Department",
      "sort": "none",
      "sortHref": "?sort=department"
    }
  ],
  "rows": [
    {
      "name": "Himanshu Dubey",
      "department": "Engineering"
    }
  ]
}

visible-caption

Rendered

Employees
Employee
Himanshu Dubey

HTML

<div class="gov-table-wrapper" tabindex="0" role="region" aria-label="Employees">
  <table class="gov-table">
    <caption class="gov-table__caption">Employees</caption>
    <thead class="gov-table__head">
      <tr>
        <th scope="col" class="gov-table__header">Employee</th>
      </tr>
    </thead>
    <tbody class="gov-table__body">
      <tr class="gov-table__row">
        <td class="gov-table__cell">Himanshu Dubey</td>
      </tr>
    </tbody>
  </table>
</div>

{
  "caption": "Employees",
  "captionVisible": true,
  "columns": [
    {
      "key": "name",
      "header": "Employee"
    }
  ],
  "rows": [
    {
      "name": "Himanshu Dubey"
    }
  ]
}

empty

Rendered

Employees
Employee

HTML

<div class="gov-table-wrapper" tabindex="0" role="region" aria-label="Employees">
  <table class="gov-table">
    <caption class="gov-table__caption gov-visually-hidden">Employees</caption>
    <thead class="gov-table__head">
      <tr>
        <th scope="col" class="gov-table__header">Employee</th>
      </tr>
    </thead>
    <tbody class="gov-table__body">
    </tbody>
  </table>
</div>

{
  "caption": "Employees",
  "columns": [
    {
      "key": "name",
      "header": "Employee"
    }
  ],
  "rows": []
}

Accessibility

Accessible name. The caption, which is visually hidden by default.

Keyboard behavior
Key	Behavior
`Tab`	Moves focus to the scroll container when the table overflows.

Every header carries scope='col', without which a cell read in isolation has no header association.
A caption is required: a screen reader user landing on the table needs to know what it is a table of.
The scroll container is focusable and labelled. A horizontally scrolling region that nothing can focus is unreachable by keyboard — a real WCAG 2.2 failure, invisible on desktop and obvious on a phone.
Sort state is announced through aria-sort, and the control is a link, so sorting works without JavaScript.
Numeric columns use tabular figures so digits align down the column.

Class names

Class names
Role	Class
`base`	`.gov-table`
`wrapper`	`.gov-table-wrapper`
`head`	`.gov-table__head`
`body`	`.gov-table__body`
`row`	`.gov-table__row`
`header`	`.gov-table__header`
`cell`	`.gov-table__cell`
`headerNumeric`	`.gov-table__header--numeric`
`cellNumeric`	`.gov-table__cell--numeric`
`caption`	`.gov-table__caption`
`sort`	`.gov-table__sort`

View the manifest for this component: packages/manifest/components/table.json