Data table

When to use

• For long lists that coaches work through: the client list, invoices, payouts, check-ins to review.
• When coaches need to sort, filter, select several rows for one action, or page through the results.

When not to use

• For a short, fixed list that needs none of that: use a plain Table.
• For a few items with rich content, such as programs with a cover and a description: use Cards.
• When there is no data yet: show an Empty state instead of an empty table with headers.

Anatomy

A data table is a composition, not one component, following shadcn's data-table recipe. TanStack Table (@tanstack/react-table v9, installed) owns the state: sorting, filtering, selection and pages. The markup is the Table component, with Button, Checkbox, Input and Dropdown menu inside it. There is no components/ui/data-table.tsx; copy the example and change the columns.

In TanStack Table v9, every feature is registered once in tableFeatures({ … }) at module scope, together with its row model. Keep features, columns and the data stable (module scope or useMemo), or the row models are rebuilt on every render.

Variants

One pattern. Leave out the parts a list doesn't need: a payout history has no selection, and a list of 8 rows has no pagination.

• Client-side: all rows are loaded, as in the example. Fine up to a few hundred rows.
• Server-side: the API sorts, filters and pages. Set manualSorting, manualFiltering and manualPagination, and pass rowCount so "Showing 11–20 of 1,240" stays right.

States

Usage guidelines

• The first data column is what coaches scan for, usually the client's name. Sort by it by default, and say so.
• Align text to the start and numbers to the end with tabular-nums, as in Table.
• Make only the columns worth sorting sortable: names, dates and amounts. A status column is easier to filter than to sort.
• Put actions for many rows in the toolbar ("Send check-in reminder") and actions for one row in its menu. Don't show both checkboxes and per-row buttons for the same action.
• Keep the page size steady (10, 25 or 50). Reset to the first page when the filter changes.
• Destructive actions in the row menu use the destructive item and open a confirmation.

Content guidelines

• Header labels are short nouns: "Client", "Program", "Last check-in", "Monthly fee". Put the unit or currency in the cell ("SAR 450"), as in Content › Money.
• The filter's label says what it searches: "Filter by client name", not "Search".
• The no-results row names the fix: "No clients match this name. Check the spelling or clear the filter."
• The count reads "Showing 1–10 of 24". In Arabic, write "عرض 1 إلى 10 من 24": a dash between two numbers is reordered in right-to-left text.
• Row action labels are verbs: "View profile", "Send check-in reminder", "Pause coaching".

Accessibility

• Table semantics stay native. Rows and cells are <tr>, <th> and <td>, so screen readers announce the column with each cell ("Monthly fee, SAR 450"). Don't use role="grid" unless you also build grid keyboard navigation.
• Sorting. Each sortable header holds a <button> whose name is the column name. The <th> gets aria-sort="ascending" or "descending" on the sorted column only. The arrow icons are aria-hidden. Because aria-sort changes are not announced reliably, the example also writes "Sorted by Client, ascending" to a visually hidden role="status" region. NVDA reads the sorted header as "Client, column header, sorted ascending, button".
• Selection. Every checkbox has a name: "Select all clients on this page", "Select Sara Al-Otaibi". A partly selected page sets the header checkbox to "indeterminate", announced as "mixed". Checkboxes are 16px; they meet WCAG 2.5.8 through the spacing around them, so don't put two in one cell.
• Row actions. The menu button is named after the row ("Actions for Sara Al-Otaibi"), not just "More", because a screen reader lists all 10 of them.
• Filter and pages. The count is a role="status" region, so typing in the filter or changing the page announces "Showing 1–5 of 5".
• Caption. Give the table a caption (here sr-only) so it can be found in a list of tables.
• When the table is wider than the screen, its container scrolls and takes focus (see Table).

RTL

• Columns run right to left: the checkbox column is on the right and the row menu on the left. text-start and text-end follow; amounts stay aligned to the end.
• The Previous and Next chevrons mirror (rtl:-scale-x-100); sort arrows point up and down and don't.
• The row menu opens with align="end", so it lines up with the menu button on either side.
• Client names and amounts stay in their own script: Western digits in both languages (QUESTIONS Q22).

Tokens used

The data table adds no tokens of its own. These are the tokens of the Table component it is built on; see Button, Checkbox and Input for the rest.

Read from components/ui/table.tsx at build time, so this list changes when the component does. Opacity modifiers such as /90 are shadcn hover and focus tints on top of the token.

• Radiusrounded-sm
• Typefont-medium
• Typetext-sm

Props

The props below are the Table parts. Sorting, filtering, selection and pagination are options of useTable; see the TanStack Table API.

Replaces in coach-admin

Related

Table, Checkbox, Badge, Empty state, Pagination, Content.