Skip to content

TkxDataGrid

import { TkxDataGrid } from 'tekivex-ui';
Basic — sortable columns + bordered
Priya Kumarpriya@example.comAdminActive
Marcus Leemarcus@example.comEditorActive
Sara Chensara@example.comViewerPending
Diego Vegadiego@example.comEditorActive
Aisha Patelaisha@example.comAdminInvited
<TkxDataGrid
data={users}
rowKey="id"
sortable
bordered
columns={[
{ key: 'name', label: 'Name', sortable: true },
{ key: 'email', label: 'Email' },
{ key: 'role', label: 'Role', sortable: true },
]}
/>
Row selection — controlled
1 of 5 rows selected
Priya Kumarpriya@example.comAdmin
Marcus Leemarcus@example.comEditor
Sara Chensara@example.comViewer
Diego Vegadiego@example.comEditor
Aisha Patelaisha@example.comAdmin

Selected IDs: ["2"]

const [selected, setSelected] = useState<string[]>([]);
<TkxDataGrid
data={users}
rowKey="id"
selectable
selectedRows={selected}
onSelectionChange={setSelected}
columns={[...]}
/>

groupBy accepts a single column key or an ordered array of keys. With an array the grid builds a nested group tree — rows are bucketed by the first key, each bucket is sub-grouped by the second, and so on. Every level’s header row shows the group value, the number of leaf rows beneath it, and each column’s aggregate computed over all leaf rows under that header, so totals roll up correctly at every level. Collapsing a header hides all of its descendants (sub-group headers and detail rows alike); re-expanding it restores the sub-groups’ own expanded/collapsed state.

<TkxDataGrid
data={orders}
rowKey="id"
groupBy={['region', 'dept']}
defaultExpandedGroups={['EMEA', groupPathKey('EMEA', 'Sales')]}
onGroupToggle={(key, expanded) => console.log(key, expanded)}
columns={[
{ key: 'region', header: 'Region' },
{ key: 'dept', header: 'Dept' },
{ key: 'name', header: 'Name' },
{ key: 'amount', header: 'Amount', aggregate: 'sum' },
{ key: 'margin', header: 'Margin', aggregate: 'avg' },
]}
/>

Keys passed to defaultExpandedGroups and received by onGroupToggle are path keys: the stringified group values from the root down, joined with GROUP_KEY_SEPARATOR (the ASCII unit separator, '\u001F'). That character cannot appear in ordinary cell text, so values containing /, |, . or any other printable character never collide with a nested path. Build keys with the exported helper rather than concatenating by hand:

import { groupPathKey, GROUP_KEY_SEPARATOR } from 'tekivex-ui';
groupPathKey('EMEA'); // 'EMEA' — level 0
groupPathKey('EMEA', 'Sales'); // 'EMEA\u001FSales' — level 1

A single-string groupBy (or a one-element array) keeps the plain, pre-existing keys — 'EMEA', not a path — so nothing changes for current callers.

  • Sorting applies inside each leaf group; group order follows the first appearance of each value in the sorted data.
  • Filtering runs before grouping, so groups with no matching rows are not rendered at any level.
  • Indent: nested headers indent by level × indentSize (default 24px), the same prop used by tree data.
  • Accessibility: every header row is role="row" with aria-level={level + 1}; detail rows carry aria-level={depth + 1}. The first cell of each header is a rowheader exposing aria-expanded and an aria-controls list of every rendered descendant row.
  • Keyboard: arrow keys move across nested headers and detail rows like any other rows. On a header cell, ArrowRight expands a collapsed group, ArrowLeft collapses an expanded one, and Enter / Space toggle.
  • childRowsKey (tree data) is still ignored when groupBy is set.
PropTypeRequiredDescription
columnsDataGridColumn<T>[]yes
dataT[]yes
rowKeystring | ((row: T) => string)yes
selectableboolean
selectedRowsstring[]
onSelectionChange(ids: string[]) => void
sortablebooleanEnable column sorting. When true, clicks sort data client-side unless onSort is also provided.
onSort(key: string, direction: 'asc' | 'desc') => voidExternal sort handler. When provided, raw data is NOT sorted internally — you must pass pre-sorted data.
loadingboolean
emptyMessagestring
stickyHeaderboolean
stripedboolean
borderedboolean
compactboolean
maxHeightnumber | string
onRowClick(row: T) => void
virtualScrollbooleanEnable virtual scrolling. Defaults to auto (enabled when data ≥ 50 rows and maxHeight is set).
rowHeightnumberRow height in pixels for virtual scrolling calculations. Default: 40
showFiltersbooleanShow column filter inputs below the header row.
filterValuesRecord<string, string>Controlled filter values keyed by column key.
onFilterChange(key: string, value: string) => voidCalled when a column filter changes.
pageSizenumberRows per page for built-in pagination. Set to 0 to disable. Default: 0 (disabled).
showExportbooleanShow a CSV export button in the toolbar.
exportFileNamestringFile name for CSV export (without .csv extension). Default: “export”.
onLoadMore() => void | Promise<void>Called when the user scrolls near the bottom. Use to fetch more data.
hasMorebooleanWhether more data is available to load. When false, sentinel is hidden.
loadingMorebooleanShow a loading skeleton at the bottom while fetching more data.
loadMoreThresholdnumberHow many pixels from the bottom to trigger onLoadMore. Default: 200
groupBystring | string[]Column key, or ordered list of keys for multi-level grouping. See Multi-level grouping.
defaultExpandedGroups'all' | 'none' | string[]Which groups start expanded. Default: 'all'. Array entries are path keys (groupPathKey).
onGroupToggle(groupKey: string, expanded: boolean) => voidFired when a group header is toggled; groupKey is the path key.
indentSizenumberPixels of indent per nesting level for tree data and nested group headers. Default: 24
  • Keyboard navigation supported on all interactive elements
  • :focus-visible outline at 2px (theme-token primary)
  • ARIA roles and properties applied per WAI-ARIA 1.2
  • Respects prefers-reduced-motion
  • Minimum 44×44 touch target where applicable

The implementation lives at src/components/TkxDataGrid.tsx.

For tree-data, column pinning, row grouping, infinite scroll, and the full prop matrix, open the playground or the DataGrid recipe.