Skip to content

Design system

Documentation

DesignPatterns / Data Table

Patterns / Data Table

Draft

Data table

A data table pattern makes search, filters, selection, pagination, and request states explicit without pretending a simple HTML table is a full table product.

On this page

Examples

Staged filtering and selection

Apply filters as one change, keep page selection explicit, and preserve the table while rows load.

Project directory

Fixture data only. Search and filter locally; this example makes no backend request.

Scroll horizontally to see all table columns.

Projects, owners, statuses, and last update times
Atlas onboardingMai NguyenActive8 min ago
Lumen researchLinh DoPaused3 days ago
Nova analyticsQuang LeActive5 days ago
1–3 of 5
Page 1 of 2

Project data table with staged filters, sorting, visible-page selection, and request states

When to use

Use this pattern when people compare rows, apply filters, and take actions on one or more records. It is a composition of the existing Card, Input, Select, Button, Checkbox, Badge, Dialog, and Table components, not a promise that column resizing, virtualization, or server-side pagination already exist.

Filters and requests

  • Keep draft filter inputs local until the person activates Apply filters; do not request data on every keystroke for a staged form.
  • When live search is truly the right interaction, debounce it and cancel or ignore stale requests.
  • Fetch a list or a bulk detail endpoint once. Never fire one request per selected row or expanded row.
  • Reset the page and selection when Apply filters changes the result set.
  • Use a bounded horizontal scroll region for a wide table on a narrow screen; keep the page itself within the viewport.

Selection

Make the scope of a bulk action visible: show the selected count, keep the select-all checkbox scoped to the current page, and name the action with its consequence. If the action is destructive, add the shared Dialog confirmation before it runs. The example’s Archive action only records a local status message; it does not change fixture rows or call a service.

Sorting and pagination

Use a Button inside each sortable column heading, put the current sort direction on the column header with aria-sort, and use a clear accessible name for each sort action. Keep the page range and current page in text. Sort values by their meaning: the example’s relative update labels use a fixed chronological order instead of alphabetic comparison. The example sorts its fixture rows locally; a real screen should connect these controls to its actual data source and preserve the server’s pagination contract.

States

Data table request and result states
StateBoundaryFeedback
loadingKeep table headers and filter context visible.Use a status message and disable duplicate selection, sorting, and paging actions.
emptyKeep the table structure if it helps orientation.Explain which filter returned no rows and how to clear it.
errorKeep filter choices when they are still safe to retry.Name the failed list and offer Retry.

The preview uses fixture data, including its retry delay and archive confirmation. It does not send requests. The Preview and Code/Copy tabs read the same source file, src/components/design/examples/source/data-table-pattern.tsx, so the copied version includes the behavior being shown. This pattern has no property playground because it has no public pattern-level props to explore.

Accessibility

  • Use a real table with a caption, column headers, and row headers when the data is tabular.
  • Give selection controls names that include the row identity; label the page and filter controls independently.
  • Expose the sort direction on the column header and keep sort actions as keyboard-accessible PhucTech Buttons.
  • Keep pagination buttons keyboard reachable and expose the current page in text, not only through disabled arrows.
  • Name and make the horizontally scrolling table region keyboard-focusable; show a short scroll hint on narrow screens.
  • Allow horizontal scrolling for a wide table at small widths; do not shrink labels until they become ambiguous.

Do and don’t

Do

Keep filter, selection, status, and pagination state explicit so the table can be tested one transition at a time.

Don’t

Build a dense grid with divs that only looks like a table or make a bulk action silently affect rows on another page.

  • CRUD defines edit and destructive actions around table rows.
  • Badge labels row status with readable text.
  • Layout & Grid sets the responsive boundary for wide data surfaces.