TkxDataGrid
import { TkxDataGrid } from 'tekivex-ui';Basic — sortable
Section titled “Basic — sortable”<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
Section titled “Row selection — controlled”Selected IDs: ["2"]
const [selected, setSelected] = useState<string[]>([]);
<TkxDataGrid data={users} rowKey="id" selectable selectedRows={selected} onSelectionChange={setSelected} columns={[...]}/>Multi-level grouping
Section titled “Multi-level grouping”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' }, ]}/>Group keys
Section titled “Group keys”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 0groupPathKey('EMEA', 'Sales'); // 'EMEA\u001FSales' — level 1A single-string groupBy (or a one-element array) keeps the plain,
pre-existing keys — 'EMEA', not a path — so nothing changes for current
callers.
Behaviour notes
Section titled “Behaviour notes”- 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"witharia-level={level + 1}; detail rows carryaria-level={depth + 1}. The first cell of each header is arowheaderexposingaria-expandedand anaria-controlslist of every rendered descendant row. - Keyboard: arrow keys move across nested headers and detail rows like
any other rows. On a header cell,
ArrowRightexpands a collapsed group,ArrowLeftcollapses an expanded one, andEnter/Spacetoggle. childRowsKey(tree data) is still ignored whengroupByis set.
| Prop | Type | Required | Description |
|---|---|---|---|
columns | DataGridColumn<T>[] | yes | |
data | T[] | yes | |
rowKey | string | ((row: T) => string) | yes | |
selectable | boolean | ||
selectedRows | string[] | ||
onSelectionChange | (ids: string[]) => void | ||
sortable | boolean | Enable column sorting. When true, clicks sort data client-side unless onSort is also provided. | |
onSort | (key: string, direction: 'asc' | 'desc') => void | External sort handler. When provided, raw data is NOT sorted internally — you must pass pre-sorted data. | |
loading | boolean | ||
emptyMessage | string | ||
stickyHeader | boolean | ||
striped | boolean | ||
bordered | boolean | ||
compact | boolean | ||
maxHeight | number | string | ||
onRowClick | (row: T) => void | ||
virtualScroll | boolean | Enable virtual scrolling. Defaults to auto (enabled when data ≥ 50 rows and maxHeight is set). | |
rowHeight | number | Row height in pixels for virtual scrolling calculations. Default: 40 | |
showFilters | boolean | Show column filter inputs below the header row. | |
filterValues | Record<string, string> | Controlled filter values keyed by column key. | |
onFilterChange | (key: string, value: string) => void | Called when a column filter changes. | |
pageSize | number | Rows per page for built-in pagination. Set to 0 to disable. Default: 0 (disabled). | |
showExport | boolean | Show a CSV export button in the toolbar. | |
exportFileName | string | File 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. | |
hasMore | boolean | Whether more data is available to load. When false, sentinel is hidden. | |
loadingMore | boolean | Show a loading skeleton at the bottom while fetching more data. | |
loadMoreThreshold | number | How many pixels from the bottom to trigger onLoadMore. Default: 200 | |
groupBy | string | 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) => void | Fired when a group header is toggled; groupKey is the path key. | |
indentSize | number | Pixels of indent per nesting level for tree data and nested group headers. Default: 24 |
Accessibility
Section titled “Accessibility”- Keyboard navigation supported on all interactive elements
:focus-visibleoutline at 2px (theme-tokenprimary)- ARIA roles and properties applied per WAI-ARIA 1.2
- Respects
prefers-reduced-motion - Minimum 44×44 touch target where applicable
Source
Section titled “Source”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.