s-m-r-t
Open the s-m-r-t source on GitHub Switch to dark color scheme
← All UI components

Collections and tables

DataTable

DataTable - A flexible, accessible data table component Features: - Sortable columns with custom sort functions - Row selection (single and multi-select) - Custom cell and header renderers via Snippets - Loading and empty states - Responsive with sticky header option - Material 3 styling with theme token support

Public export

typescript 
import { DataTable } from '@happyvertical/smrt-ui/data';
Import path
@happyvertical/smrt-ui/data
Props
57
Props described
57 of 57
Bindable state
4
Callback events
7
Verified release
0.57.40

Props

NameTypeRequiredDescription
density'comfortable' | 'touch'NoSort-control and pager target density; omit to inherit ThemeProvider.
responsiveMode'scroll' | 'hide-columns'NoOpt-in container-width column collapse; default keeps horizontal scrolling.
responsiveBreakpointnumberNoContainer-width threshold in pixels for narrow mode (default 800).
responsiveColumnMinWidthnumberNoTarget width per retained column in narrow mode (default 160 pixels).
dataT[]YesData rows
columnsDataTableColumn<T>[]YesColumn definitions
rowKeyDataTableRowKey<T>NoUnique key accessor for rows
agentAddressablebooleanNoDeclares that a DataSurface or agent will address rows. Such tables must provide `rowKey`, even if they do not render selection controls.
selectablebooleanNoEnable row selection
selectedSet<string | number>NoSelected row keys
onSelectionChange(selected: Set<string | number>) => voidNoSelection change callback
onRowClick(row: T, index: number) => voidNoRow click callback
rowLabel(row: T, index: number) => stringNoSupplies the accessible label used for a row's selection and expansion controls. Defaults to the 1-based display row number.
sortablebooleanNoEnable sorting
sortSortStateNoCurrent sort state
onSortChange(sort: SortState) => voidNoSort change callback
sortClearablebooleanNoWhether a third activation of a sorted header clears the sort (asc → desc → none; the default). `false` toggles asc ⇄ desc so the list always keeps one defined order.
manualSortingbooleanNoParent owns sorting and supplies already-sorted rows.
filterFn(row: T, index: number) => booleanNoOptional client-side row filter.
pagenumberNoCurrent 1-based page. Pagination is enabled when pageSize is set.
pageSizenumberNoRows per page.
manualPaginationbooleanNoParent owns pagination and supplies only the current page.
virtualizationDataTableVirtualizationOptionsNoOpt-in fixed-height virtualization for the data body. It requires rowKey and falls back to the normal semantic body when expanded rows are enabled.
totalRowsnumberNoTotal server row count when manualPagination is enabled.
onPageChange(page: number) => voidNoPage change callback.
expandedSet<string | number>NoControlled set of expanded row keys.
onExpandedChange(expanded: Set<string | number>) => voidNoExpansion change callback.
canExpand(row: T, index: number) => booleanNoPredicate controlling which rows can expand.
expandedContentSnippet<[{ row: T; index: number; }]>NoExpanded row content.
toolbarSnippetNoOptional content above the table.
footerSnippet<[{ rows: T[]; }]>NoOptional full-width table footer content.
structuralRowsreadonly DataTableStructuralRow<T>[]NoGeneric report-like rows rendered independently from data row interactions.
summariesDataTableSummaries<T>NoColumn summaries: a `<tfoot>` row with a `count`, `sum` or `avg` per column id, or a function of the rows returning the cell text. Computed over every filtered row (all pages; only the given rows under manual pagination). A `sum` / `avg` column without an explicit `align` is right-aligned. Rendered after any `footer` structural rows.
summaryLabelstringNoLabel of the summaries row (default "Total", localized).
visibleColumnIdsSet<string>NoControlled visible column ids. Column.hidden is still respected.
controllerDataTableControllerNoHeadless controller used by rendered interactions and programmatic commands. When supplied, it takes precedence over `state` and the legacy bindables.
stateDataTableViewStateInputNoExplicit controlled serializable state when no external controller is supplied.
initialStatePartial<DataTableViewState>NoInitial serializable state for uncontrolled controller-backed tables.
onStateChange(state: DataTableViewState, command: DataTableCommand) => voidNoCalled after a controller command proposes or applies a new state.
modesPartial<DataTableModes>NoExplicit ownership for local or caller-supplied filtering, sorting, and paging.
dataSurfaceDataTableDataSurfaceOptionsNoRegisters this mounted instance only when explicitly supplied.
loadingbooleanNoThe initial loading state. When rows are already present, loading keeps them interactive and is announced as a refresh instead of replacing them.
refreshingbooleanNoExplicitly announces a refresh while rendered rows remain available.
stalebooleanNoMarks rendered rows as stale while a caller refreshes them.
partialResultsbooleanNoMarks rendered rows as a partial result set.
errorDataTableLoadError | nullNoLoad failure shown without discarding already rendered rows.
onRetry() => voidNoInvoked by the localized retry button when a load error is present.
emptySnippetNoEmpty state content
rowClass(row: T, index: number) => stringNoCustom row class function
size'sm' | 'md' | 'lg'NoTable size variant
stripedbooleanNoEnable striped rows
hoverablebooleanNoEnable hover highlight
stickyHeaderbooleanNoEnable sticky header
phoneLayout'scroll' | 'cards'NoHow the table looks on phones (48rem and under): `scroll` keeps the table (scrolling sideways when it is wider than the screen), `cards` makes each row its own block of stacked cells and hides the column heads, so give the page another way to sort (a `ListSortSelect`).
captionstringNoTable caption for accessibility
densebooleanNoDense mode (reduced padding)
cellSnippet<[ { column: DataTableColumn<T>; row: T; value: unknown; index: number; } ]>NoGlobal cell renderer - takes precedence over column.cell

Bindable state

  • bind:selectedSet<string | number>
  • bind:sortSortState
  • bind:pagenumber
  • bind:expandedSet<string | number>

Callback events

  • onSelectionChange(selected: Set<string | number>) => void
  • onRowClick(row: T, index: number) => void
  • onSortChange(sort: SortState) => void
  • onPageChange(page: number) => void
  • onExpandedChange(expanded: Set<string | number>) => void
  • onStateChange(state: DataTableViewState, command: DataTableCommand) => void
  • onRetry() => void

Examples and explanation

Data Table Run the canonical package-owned example in the Playground. UI showcase Read the curated UI story for mechanism and usage guidance. smrt-ui package reference See package status, version, limitations, and all public subpaths.