DataTable

Coordinate querying, sorting, and pagination with composable toolbar, table, and pagination controls.

We are building SnowUI components into interfaces people can use directly in AI conversations. Conversational UI is still in development; this page demonstrates website usage. Supported chat platforms and component versions will be announced after verification. Generating and using SnowUI interfaces inside AI conversations is completely free. It is not a project, uses no project or developer-seat quota, and requires no SnowUI registration, activation, or paid proof.

How to use

Use DataTable for file or record lists that need search, filtering, sorting, pagination, selection, or action columns. It coordinates data state with TableToolbar, the Table family, and Pagination. Use Table for display only. Enable selection explicitly and use stable rowKey and matching TableRow.rowId; configure actions for action columns. The page owns requests and data formatting.

client mode processes data locally; server mode receives page-provided requests and results. children receives the current render state.
Enable selection and actions explicitly. rowKey defaults to an index; for sorting or data updates, use a stable business ID and match it in TableRow.rowId.
Pages start at 1. Initial loading, background refreshing, and incremental loadMore are distinct states.

Import

import { DataTable } from '@snowui-design-system/components';

Usage

Divided

Selection

Server pagination

Load more

API Reference

Property	Type	Default	Example	Description
`rows`	`T[]`	`[]`	`rows={rows}`	Current data rows.
`mode`	`DataTableMode`	`"client"`	`mode={value}`	Choose local client slicing or controlled server mode. Defaults to client.
`sorters`	`Record<string, Sorter<T>>`	`{}`	`sorters={sortersOptions}`	Explicit sort functions needed only for complex derived columns.
`searcher`	`Searcher<T>`	`—`	`searcher={value}`	Override client search behavior. By default, it matches shallow string and number fields.
`filterer`	`Filterer<T>`	`—`	`filterer={value}`	Override client filtering. By default, fields are matched by equality.
`rowKey`	`(row: T, index: number) => string \| number`	`(_row, index) => index`	`rowKey={(value) => { /* handle value */ }}`	Stable row identity reader. Defaults to the row index; use a business ID when sorting or changing data.
`sort`	`TableSortState`	`defaultSort`	`sort={value}`	Current sort column and direction. Client mode sorts locally; the caller handles it in server mode.
`defaultSort`	`TableSortState`	`—`	`defaultSort={value}`	Compatibility default for one initial sort column. New code should prefer defaultSort on TableHead.
`query`	`string`	`""`	`query="Example"`	Current search text. Client mode searches locally; the caller handles it in server mode.
`filters`	`Record<string, unknown>`	`{}`	`filters={filtersOptions}`	In client mode, filter fields by equality or array containment.
`page`	`number`	`1`	`page={42}`	Current one-based page number, clamped to the valid range in render state.
`pageSize`	`number`	`10`	`pageSize={42}`	Rows per page. Changing it resets to page 1.
`totalRows`	`number`	`—`	`totalRows={42}`	Total row count in server mode.
`loading`	`boolean`	`false`	`loading`	Initial loading state passed to the table and render state.
`refreshing`	`boolean`	`false`	`refreshing`	Background refresh state that retains existing rows and appears in render state.
`loadMore`	`DataTableLoadMore<T>`	`—`	`loadMore={value}`	Incremental data source. The request includes offset, limit, and AbortSignal.
`loadMoreSize`	`number`	`5`	`loadMoreSize={42}`	Maximum rows requested in each incremental load.
`loadMoreMode`	`DataTableLoadMoreMode`	`"manual"`	`loadMoreMode={value}`	Call state.loadMore() manually, or let an internal sentinel at the table end trigger automatically. Defaults to manual.
`loadMoreThreshold`	`number`	`80`	`loadMoreThreshold={42}`	In auto mode, pixels scrolled beyond the table end before triggering.
`loadMoreThrottleMs`	`number`	`500`	`loadMoreThrottleMs={42}`	Confirmation delay after first entering the auto trigger zone and minimum interval between requests. Leaving during the initial wait cancels it.
`hasMore`	`boolean`	`—`	`hasMore`	Explicitly state whether more rows exist. Otherwise derive from totalRows first, then returned batch size.
`error`	`unknown`	`—`	`error={value}`	External error, taking precedence over incremental-load errors in state.error. The component does not generate business error copy.
`resetPageOnQuery`	`boolean`	`true`	`resetPageOnQuery`	Reset the page to 1 when query or filters change.
`onSortChange`	`(sort: TableSortState \| undefined) => void`	`—`	`onSortChange={(value) => { /* handle value */ }}`	Callback when sort changes; receives undefined when sorting is cleared.
`onQueryChange`	`(query: string) => void`	`—`	`onQueryChange={(value) => { /* handle value */ }}`	Callback when query text changes.
`onPageChange`	`(page: number) => void`	`—`	`onPageChange={(value) => { /* handle value */ }}`	Callback when the one-based page changes.
`onPageSizeChange`	`(pageSize: number) => void`	`—`	`onPageSizeChange={(value) => { /* handle value */ }}`	Callback after normalized page size changes.
`onStateChange`	`(state: DataTableRenderState<T>) => void`	`—`	`onStateChange={(value) => { /* handle value */ }}`	Callback when render state updates, including visible rows, pagination, selection, and loading state.
`state`	`DataTableRenderState<T>`	`—`	`state={value}`	Bindable current render state.
`variant`	`DataTableVariant`	`"divided"`	`variant={value}`	Row appearance: zebra stripes or dividing lines. Defaults to divided.
`selectedRowIds`	`Array<string \| number>`	`[]`	`selectedRowIds={selectedRowIds}`	Selected row IDs; DataTable owns selection state.
`selection`	`boolean`	`false`	`selection`	Show a checkbox selection column. When false, Head and Cell entries with as="selection" do not render.
`actions`	`boolean \| DataTableActionsConfig<T>`	`false`	`actions={value}`	Show an action column. A configuration object generates OverflowActions in an empty actions Cell.
`horizontalScroll`	`boolean`	`true`	`horizontalScroll`	Pass horizontal overflow strategy to Table. With false, hide eligible ordinary columns from right to left, then scroll if protected columns still exceed width.
`roleLayout`	`TableRoleLayout`	`"auto"`	`roleLayout={value}`	Keep role columns in place when wide, then move them to a hover overlay when space is short. column or overlay fixes the layout.
`roleOverlayLayers`	`number`	`4`	`roleOverlayLayers={42}`	Number of progressive blur layers in the role overlay.
`roleOverlayBlurMode`	`TableRoleOverlayBlurMode`	`"progressive"`	`roleOverlayBlurMode={value}`	Overlay blur algorithm; defaults to progressive.
`roleOverlayUniformFeather`	`number`	`0.3`	`roleOverlayUniformFeather={42}`	Inner feather ratio in uniform overlay mode.
`onRowPreview`	`(row: T, state: DataTableRenderState<T>, event: MouseEvent) => void`	`—`	`onRowPreview={(value) => { /* handle value */ }}`	When provided, clicking empty space in a TableRow opens a row preview. Without it, that click does nothing.
`onSelectedRowIdsChange`	`(rowIds: Array<string \| number>) => void`	`—`	`onSelectedRowIdsChange={(value) => { /* handle value */ }}`	Complete selected-ID snapshot after selection changes.
`children`	`Snippet<[DataTableRenderState<T>]>`	`—`	`<DataTable>Content</DataTable>`	Table, toolbar, and pagination composition receiving the current render state.