Skip to main content

Table

A structured way to display data in rows and columns. Rows and cells render exactly what you put in them, with no sorting, filtering, selection, or pagination built in.

When to use

  • Show static tabular content with a thin, semantic primitive: invoice summaries, pricing matrices, reference tables in documentation.
  • Prefer DataTable for dynamic, application data: anywhere users need to sort, filter, paginate, select, or click rows. DataTable is built on top of Table and powered by TanStack Table.
  • Prefer DescriptionList to show one record as label and value pairs.

Composition

Compose the parts of a Table together to build your own:

Table.Root└── Table.Element    ├── Table.Caption    ├── Table.Head    │   └── Table.Row    │       └── Table.Header    ├── Table.Body    │   └── Table.Row    │       └── Table.Cell    └── Table.Foot

Guidelines

Each row a table renders costs mount and layout time. A table that renders every row of a large list blocks typing and clicks while it mounts, and a slow device feels it first.

  • Paginate a list that can grow past 100 rows. Show 100 rows or fewer on a page, and default to a smaller page, such as 20.
  • Search and filter the whole list, then paginate the result. Pagination limits what renders, not what a search finds.
  • Show the count with PaginationRange, so a reader knows how many rows match and where the page sits.
  • Return to the first page when a search, a filter, or a sort changes. useOffsetPagination does this when the filtered listSize changes. Call goToFirstPage() when only the sort changes.
  • Keep the page in the URL when a reader leaves the table and comes back, such as from a detail page. Pass page and onPageChange to useOffsetPagination.
  • Paginate before you virtualize. A page of 100 rows mounts fast, and the browser's find in page still sees every row on it.
  • Clip a long ID or URL with TruncatedText, which keeps the end of the value. Give the table table-layout: fixed and a width, or the column grows to the full value.

Use DataTable when a reader also sorts or selects rows. The same guidelines apply.

Pagination

Slice the rows with useOffsetPagination and getOffsetPaginatedSlice. Then compose CursorPagination and PaginationRange under the table. The count line is a live region, so a screen reader hears the new range when the page changes.

API Reference

The Table is a structured way to display data in rows and columns. The API matches the HTML table element 1:1. It is composed of several sub-components.

Table.Root

Root container for all Table sub-components. Should be the parent of all other table sub-components. It draws the border and rounded corners, and scrolls wide content horizontally with a fading scroll edge.

All props from div. ref lands on the inner scroll container, so you can read or set its scroll position; every other prop lands on the outer element.

Table.Root stamps these data attributes on its outer element for your own CSS to target:

AttributeValueDescription
data-x-overflow"true" | "false"Whether the content is wider than the container. Always present, so match the value, not the attribute.
data-x-scroll-end"true" | "false"Whether an overflowing container is scrolled to its right edge. Always present.
data-sticky-activepresent, or absentPresent only while the container overflows and is not scrolled to the end. DataTable's pinned action column keys its shadow off this through group-data-sticky-active/table:.

Table.Element

The API matches the HTML table element 1:1.

Permitted content in this order:

  1. optional: Table.Caption
  2. 0 or more: colgroup elements
  3. optional: Table.Head
  4. either one of the following:
    • 0 or more: Table.Body
    • 0 or more: Table.Row
  5. optional: Table.Foot

All props from table.

Table.Head

Container for the table's column headers. Encapsulates a set of Table.Rows, indicating that they comprise the head of a table with information about the table's columns.

All props from thead.

Table.Body

Encapsulates a set of Table.Rows, indicating that they comprise the body of a table's (main) data. A body row highlights under the pointer and when a link or button inside it has visible focus, so a keyboard user sees the same row-scale target as a mouse user.

All props from tbody.

Table.Foot

Encapsulates a set of Table.Rows, indicating that they comprise the foot of a table with information about the table's columns. This is usually a summary of the columns, e.g., a sum of the given numbers in a column.

All props from tfoot.

Table.Row

Defines a row of cells in a table. The row's cells can then be established using a mix of Table.Cell and Table.Header components.

All props from tr.

Table.Header

Defines a cell as the header of a group of table cells and may be used as a child of a Table.Row. scope defaults to "col"; pass scope="row" for a header cell inside a body row.

All props from th.

Table.Cell

Defines a cell of a table that contains data and may be used as a child of a Table.Row.

All props from td.

Table.Caption

Specifies the caption (or title) of a table, which gives the table its accessible name.

All props from caption.