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
DataTablefor dynamic, application data: anywhere users need to sort, filter, paginate, select, or click rows.DataTableis built on top ofTableand powered by TanStack Table. - Prefer
DescriptionListto show one record as label and value pairs.
Composition
Compose the parts of a Table together to build your own:
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.
useOffsetPaginationdoes this when the filteredlistSizechanges. CallgoToFirstPage()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
pageandonPageChangetouseOffsetPagination. - 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 tabletable-layout: fixedand 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:
Table.Element
The API matches the HTML table element 1:1.
Permitted content in this order:
- optional:
Table.Caption - 0 or more:
colgroupelements - optional:
Table.Head - either one of the following:
- 0 or more:
Table.Body - 0 or more:
Table.Row
- 0 or more:
- 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.