DataTable

Virtualized continuous or paginated data with phone cards, selection, layouts, groups, and trees.@gemologic/sheen-table · data

Playground

This example has no scalar controls. Its validated source remains interactive below.

Accounts
not sorted	not sorted
Alpha	12
Beta	34

Alpha

Amount: 12

Beta

Amount: 34

<DataTable data={rows} columns={columns} getRowId={row => row.id} caption="Accounts" pagination={false} mobileLayout={{ pageSize: 20, titleColumn: "name" }} initialViewportHeight={160} />

Variant matrix

Bounded continuous data

Accounts
not sorted	not sorted
Alpha	12
Beta	34

Alpha

Amount: 12

Beta

Amount: 34

Summarize an accepted constant field

Active accounts
not sorted
Alpha

Anatomy

Package

@gemologic/sheen-table

Source

packages/table/src/DataTable.tsx

Tokens

--sheen-table-row-h
--sheen-color-border
--sheen-color-bg
--sheen-color-bg-raised

Accessibility

Role: table or treegrid, row, gridcell, columnheader, list, listitem, checkbox, toolbar, menu, separator, navigation, statusKeyboard: Tab, Shift+Tab, Shift+F10, ContextMenu, ArrowLeft, ArrowRight, ArrowUp, ArrowDown, Home, End, PageUp, PageDown, Enter, Space, Shift+Space, Control+A, Meta+A

Do

Use continuous client mode for bounded local datasets.
Use numbered server pagination for large or expensive remote results.
Enable mobileLayout when a table must be functional on phones; tune its bounded continuous page size to row complexity.
Supply full-query counts and aggregates when the server delegates grouping.
Provide initialResult when server rendering already fetched the accepted page.
Define row actions once so context, card overflow, and bulk paths cannot drift.
Return complete server exports from onExport rather than walking pages in the component.
Return explicit conflict results from onCellCommit instead of parsing transport error text.
Change selection.resetKey, hierarchy.resetKey, export.resetKey, and editResetKey when the user's authorization or account boundary changes.
Keep column controls enabled when users can drag, so every layout action has a keyboard path.

Do not

Do not use pagination=false for an incomplete server response or infinite fetching.
Do not render an unbounded phone card list; mobileLayout limits continuous pages to at most 100 cards.
Do not calculate group totals from one server page.
Do not paginate, sort, filter, or export one server page locally and present it as the complete query.
Do not materialize all-matching selection by walking server pages or offer it for a hierarchy whose subtree query cannot be represented.
Do not request server data for visibility, order, pin, or width-only changes.

Generated props

Name	Type	Default	Description
`mode`	`"client" \| "server"`	`client`	Client processes complete supplied data; server delegates the full query and requires pagination plus onStateChange.
`data`	`readonly Row[]`	—	Complete bounded client dataset. Available only in client mode.
`initialResult`	`DataTableResult<Row>`	—	Optional authoritative server result used for SSR without a duplicate hydration request. Delegated grouping includes groups for the accepted page.
`onStateChange`	`(state: TableState, signal: AbortSignal) => Promise<DataTableResult<Row>>`	—	Server request adapter receiving complete state and an AbortSignal. Available only in server mode.
`onExport`	`(request: TableExportRequest, signal: AbortSignal) => Promise<Blob>`	—	Optional server adapter returning a Blob for the captured accepted state and immutable selection. Server export UI is hidden without it.
`refreshKey`	`string \| number`	—	Server-only invalidation key. Changes revalidate the latest requested or accepted query, retaining rows, layout, drafts, selection, and scroll. The initial value does not fetch; changing it supersedes pending transport.
`columns` *	`SheenColumns<Row>`	—	Opaque column definitions returned by defineColumns. Noneditable custom cells may declare cellDependencies for extra row fields; accessor values always invalidate, and omitted dependencies retain whole-row invalidation. Include fields captured by event handlers and replace row data immutably.
`getRowId` *	`(row: Row) => string`	—	Returns a stable, unique, nonempty row ID.
`caption` *	`string`	—	Required accessible table caption, visually hidden by default.
`variant`	`DataTableVariant`	—	Standalone frame or application-pane integration; omission follows context.
`density`	`DataTableDensity`	—	Optional table-local compact, comfortable, or spacious density. Omission inherits the surrounding application density.
`pagination`	`TablePagination`	—	False selects complete continuous results; page state selects numbered pagination. Client defaults false and server requires an explicit choice.
`initialState`	`DataTableInitialState`	—	Optional initial query and column-layout state; pagination remains configured by the pagination prop.
`filter`	`FilterNode`	—	Optional app-owned accepted filter applied reactively without remounting retained rows; onAcceptedStateChange synchronizes table-authored changes.
`rowHeight`	`string`	`var(--sheen-table-row-h)`	CSS length for the fixed row block size or the minimum measured variable-row size.
`variableRowHeight`	`boolean`	`false`	Allows content-driven row heights and measures each realized row.
`estimatedRowHeight`	`number`	`34`	Positive CSS-pixel estimate used before measurement. Defaults to the active compact, comfortable, or spacious row token.
`initialViewportHeight`	`number`	`400`	Positive CSS-pixel viewport size used for deterministic server rendering and hydration.
`class`	`string`	—	Optional class merged onto the table region.
`onAcceptedStateChange`	`(state: TableState) => void`	—	Receives accepted query states and locally committed layout states; transient resize frames are excluded.
`onRowActivate`	`(row: Row) => void`	—	Enables roving row focus and receives Enter activation for the focused row.
`selection`	`DataTableSelectionOptions<Row>`	—	Enables table-owned multiple selection, optional authorization-boundary resetKey, and immutable explicit-ID or query/exclusion payloads.
`actions`	`readonly DataTableAction<Row>[]`	—	One validated action model rendered in the bottom selection bar and each accepted row's context menu.
`mobileLayout`	`boolean \| DataTableMobileLayoutOptions`	—	Opt-in card presentation below 768px. Continuous results use local bounded pages of 20 cards by default; numbered tables keep their configured page.
`grouping`	`DataTableGroupingOptions`	—	Groups a complete continuous client view, or validates explicit full-query group metadata supplied with each delegated server page.
`hierarchy`	`DataTableHierarchyOptions<Row>`	—	Provides synchronous children and optional app-loaded subtrees with independent cancellation, retry, stale-response rejection, and authorization reset.
`search`	`false \| DataTableSearchOptions`	—	Configures automatic search over explicitly searchable columns, or false disables it; options supply label, placeholder, debounce, shortcut, and an opt-in Exact mode that matches a literal phrase within one searchable column.
`filterBar`	`boolean \| DataTableFilterBarOptions`	`true`	Shows typed filters declared by columns; options may inject an isolated date editor without adding it to the table bundle.
`columnControls`	`boolean`	`true`	Shows the keyboard-accessible visibility, ordering, pinning, auto-fit, and width-reset menu.
`summarizeColumns`	`readonly string[]`	—	Opt-in filterable, noneditable, nonsensitive accessor IDs. Exact accepted constraints replace eligible visible columns with labeled full-query counts and a restore action. Never samples page rows or facets, never rewrites saved visibility, and retains at least one column. Explicit restoration lasts for this table owner.
`export`	`false \| DataTableExportOptions`	—	Client export is enabled by default; false hides it, while options constrain formats and set a filename base.
`onCellCommit`	`(request: DataTableCellCommitRequest<Row>, signal: AbortSignal) => Promise<CellCommitResult<ColumnValue, string>>`	—	Required by editable columns; receives row/column context, a per-cell commit ID, previous/value snapshot, and AbortSignal, then reports acceptance or an explicit conflict.
`editResetKey`	`string \| number`	—	Discards drafts, conflicts, failed attempts, and pending commits when an account or permission boundary changes.

Native Solid/HTML attributes remain available and are omitted from this authored-prop view.