DataTable

Data table with sorting, selection, and column management. Powered by TanStack Table.

Setup

import { DataTable } from '@fragments-sdk/ui';

Examples

Default

Basic data table with status badges and role columns

Loading preview...

Rich Cells

Custom cells with avatars, stacked text, and column sizing

Loading preview...

Sortable

Click column headers to sort ascending or descending

Loading preview...

Checkbox Selection

Select rows with header checkbox for select-all and individual row checkboxes

Loading preview...

Expandable Rows

Hierarchical data with collapsible sub-rows, like a file tree

Loading preview...

With Filters

Combine with search input and menu dropdowns for filtered views

Loading preview...

Clickable Rows

Rows respond to click and keyboard activation

Loading preview...

Striped

Alternating row backgrounds for dense data

Loading preview...

Empty State

Display when no data matches the current filters

Loading preview...

Props

PropTypeDefaultDescription
columnsRequiredarrayNot setColumn definitions
dataRequiredarrayNot setData rows to display
getRowIdfunctionNot setUnique key extractor for each row
sortablebooleanfalseEnable column sorting
sortingarrayNot setControlled sorting state
onSortingChangefunctionNot setSorting change handler
selectablebooleanfalseEnable row selection
showCheckboxbooleanfalseShow checkbox column for row selection (requires selectable)
rowSelectionobjectNot setControlled row selection state
onRowSelectionChangefunctionNot setRow selection change handler
onRowClickfunctionNot setHandler for row clicks/keyboard activation. Called as (row, event)
getSubRowsfunctionNot setExtract sub-rows for expandable tree tables
expandedunionNot setControlled expanded state
onExpandedChangefunctionNot setExpanded state change handler
emptyMessagestringNo data availableMessage when no data
sizeenumsmmdmdTable density
captionstringNot setVisible caption for the table
captionHiddenbooleanfalseHide caption visually but keep it for screen readers
stripedbooleanfalseShow alternating row backgrounds
borderedbooleanfalseWrap table in a bordered container
wrapperClassNamestringNot setAdditional class name for the outer wrapper div
wrapperPropsobjectNot setProps forwarded to the outer wrapper div (id, aria-*, data-*, handlers)

Usage Guidelines

When to use

  • Displaying structured, tabular data with sorting
  • Data that users need to scan, compare, and act upon
  • Lists with multiple attributes per item that need sorting or selection
  • Data-rich tables requiring column sizing and row clicks
  • Hierarchical data with expandable sub-rows

When not to use

  • Simple static tables (use Table component)
  • Simple lists (use List component)
  • Card-based layouts (use Grid with Cards)
  • Small screens (consider card or list view)

Best practices

  • Keep columns to a reasonable number (5-7 max)
  • Use consistent alignment (numbers right, text left)
  • Provide meaningful empty states
  • Consider mobile responsiveness
  • Use showCheckbox for bulk selection workflows
Accessibility
  • Proper table semantics with headers
  • Sortable columns are keyboard accessible
  • Row selection checkboxes include aria-labels
  • Expand/collapse buttons have aria-expanded state