DataTable

A data grid: sort, search, filter, resize, reorder, pin, group, select, edit, page or virtualize, save views and export.

Example
import { DataTable, DataTableColumn, RowAction } from "@elements/ui/data-table";

const COLUMNS: DataTableColumn[] = [
  { key: "status", type: "tag", options: STATUSES, facet: "select" },
  { key: "email", header: "Email", rowHeader: true },
  { key: "amount", type: "currency", summary: "sum", editable: true },
];

<DataTable data={payments} columns={COLUMNS} label="Payments"
           selection="multiple" selected={state.selected}
           actions={ACTIONS} onSave={(changes) => persist(changes)} />

<!-- a LiveView stays live: rows patch in place, edits call payments.update() -->
<DataTable data={payments} columns={COLUMNS} editMode="direct" />

Parts

Part	What it is
DataTable	The whole grid: toolbar, role=grid (treegrid when rows nest) table, footer. Data driven from data and columns.
.data-table-toolbar	Search, faceted filters, the filter builder, Reset; Add row, Group, View, Views and Export.
.data-table-grid	role=grid, or treegrid when rows nest or expand. One CSS grid whose columns every row shares through subgrid.
.data-table-header	role=columnheader: a menu button (sort, pin, group, move, width, hide), a drag grip and a resize handle.
.data-table-row / .data-table-cell	role=row and role=gridcell (rowheader for a column with rowHeader).
.data-table-summary-row	The summary row: an aggregate per column over the filtered rows.
.data-table-detail-row	Under an open row with detail: the detail slot.
.data-table-footer	The selection count or row range, unsaved changes with Save and Discard, rows per page and the pager.
DataTableColumn	A column: key or value, header, type (text, number, currency, percent, date, datetime, time, boolean, tag, tags, link, email, phone, progress, rating, avatar, image, json, bigint, multiline, markdown, html: inline HTML cut down to safe formatting), format, cell, options, align, background (a tint, or a function of the value for a conditional one), sorting (sortFn by name, such as text, textCaseSensitive, alphanumeric and alphanumericCaseSensitive, or a comparator; sortDescFirst, sortUndefined, invertSorting, sortByOptions, sortMode: raw or the displayed text), filtering (facet, bucket), sizing, pinning, grouping, aggregate and summary (a built-in by name, a custom { label, fn }, or several), aggregationValue, editing (editor, min, max), validation, cell selection (cellSelection) and cell spanning (spanRows, spanColumns, spanning).
columnsFromData(rows, { sample, exclude })	Generates columns from the data, as a regenerate columns action would: one per field found in any row, typed by its values, with a header from the key.
RowAction	An item in a row's menu (label, icon, variant, separator, hidden, disabled, onSelect); inline also shows it as an icon button on the row.

Slots

Slot	Content
detail	The open row's detail (with detail). Read detailRow in it.
empty	Replaces emptyText when no row matches.
tools	Extra toolbar controls, such as a custom toolbar button, at the start of the toolbar's end group.

Keyboard

Keys	Action
Tab	Into the grid (one stop), then out. Inside an edited cell: the next widget.
ArrowUp / ArrowDown / ArrowLeft / ArrowRight	Move one cell. Virtual rows scroll the next row into view.
Home / End	First or last cell of the row.
Ctrl + Home / Ctrl + End	First cell of the grid, last cell of the grid (with virtual rows, the last row of all scrolls in).
PageUp / PageDown	Move ten rows.
Enter / F2	On a cell with an editor or several controls: edit it. On a header: open its menu. On a row: onRowAction.
A letter or digit	On an editable text cell: start editing with that key.
Enter (editing)	Commit the edit and return to the cell.
Escape (editing)	Restore the value; again to return to the cell.
Space	On a checkbox cell: toggle it (row selection, a boolean edit).
Shift + Space	Select the focused row.
Ctrl + A	Select every row (again to clear).
Shift + click	On a checkbox: select the range from the last one. On a header: add the column to the sort. isRowRangeSelectionEvent and isMultiSortEvent pick other keys.
ArrowLeft / ArrowRight, Home / End in the toolbar	Move between the toolbar's buttons, which are one Tab stop (APG toolbar). The search field keeps its own stop.
Shift + Enter / Shift + Space on a header	Add the column to the sort without opening its menu.
Alt + ArrowLeft / ArrowRight	On a header: narrower or wider by 10px (Shift: 50px).
Ctrl + Alt + ArrowLeft / ArrowRight	On a header: move the column.
Alt + ArrowRight / ArrowLeft	On a group or tree row's cell: expand or collapse it.
Shift + Arrow (cellSelection)	Extend the selected range of cells.
Ctrl + Space (cellSelection)	Select the column of the focused cell.
Ctrl + A (cellSelection)	Select every cell (when rows are not selectable).
Ctrl + C (cellSelection)	Copy the selected cells as tab separated text.
Escape (cellSelection)	Clear the selected cells.
Delete, Backspace (cellSelection, editable)	Clear the selected cells.
Ctrl + X, Ctrl + V (cellSelection, editable)	Cut the selected cells; paste tab separated text from the selection, or one value into every selected cell.
Ctrl + Z, Ctrl + Shift + Z (cellSelection, editable)	Undo and redo the last edit, paste, clear or cut.
Enter, Tab in an editor (cellSelection)	Commit and move down or right; Shift moves up or left.
Ctrl + D, Ctrl + R (cellSelection, editable)	Fill the selected cells down from their top row, or right from their first column.
Ctrl + M (cellSelection, mergeable)	Merge the selected cells, or unmerge the merged cells they touch.
Enter, Tab, Escape in the value bar	Write the value and move down or right (Shift: up or left); Escape restores it and returns to the cell.
Space, ArrowUp / ArrowDown, Space (row handle)	Lift a row, move it, drop it (rowReorder); Escape cancels.

Data attributes

Attribute	Values	On	Description
data-density	"dense" | "compact" | "default" | "comfortable"	.data-table
data-sticky	present with height	.data-table
data-scrolled-start / data-scrolled-end	present	.data-table	Rows scroll under pinned columns: the edge shadow.
data-state	"selected"	.data-table-row
data-pinned	"top" | "bottom"	.data-table-row
data-tone	the rowTone	.data-table-row
data-expanded	"true" | "false"	.data-table-row	On rows that expand.
data-pin	"start" | "end"	header and cell
data-sorted	"asc" | "desc"	.data-table-header
data-dragging / data-drop	present	.data-table-header	A header being dragged, and where it would drop.
data-type	the column type	.data-table-cell
data-editable / data-editing / data-edited / data-invalid	present	.data-table-cell
data-selected	present	.data-table-cell	In the selection (cellSelection).
data-edges	"top right bottom left" (any)	.data-table-cell	The selection's outer sides at this cell (getSelectionEdges).
data-covered	"row" | "col"	.data-table-cell	Another cell's span covers this one (cell spanning).
data-dragging / data-drop-row	present	.data-table-row	A row being moved (rowReorder), and the row it would take the place of.
data-cell-selection	present	.data-table	cellSelection is on.
data-tint	"success" | "warning" | "danger" | "info" | "accent" | "muted"	.data-table-cell	The column's background (background).
data-merged	present	.data-table-cell	A merged block (merges): its content is centered.
data-fill	present	.data-table-cell	A fill handle drag would write this cell.

Accessibility

• role=grid with aria-label, aria-rowcount (header, rows, summary) and aria-colcount; rows carry aria-rowindex, so paged and virtual rows announce their place in the whole set.
• Headers and cells carry aria-colindex in display order, and arrows, Home and End follow it, so a pinned or moved column is heard and reached where it is.
• Text cut short by its column ends in an ellipsis and shows in full as its title on hover.
• One Tab stop; arrow keys move between cells (WAI-ARIA data grid). A cell with one checkbox or button gives it the focus; a cell with an editor is entered with Enter, F2 or a typed key and left with Escape.
• Sortable headers carry aria-sort; sorting, saves and errors are announced in a live region.
• aria-multiselectable on the grid and aria-selected on rows with selection; the select-all box shows the mixed state natively.
• Tree, grouped and detail tables are a treegrid: every row carries aria-level (root rows 1) and expandable rows aria-expanded; a group row is named by its value and count.
• Editable grids mark the other cells aria-readonly; an invalid edit sets aria-invalid and shows its message in an alert.
• loading sets aria-busy on the grid.
• With cellSelection the grid is aria-multiselectable and each data cell carries aria-selected.
• A merged cell (cell spanning) carries aria-rowspan or aria-colspan and is one keyboard stop; the slots it covers are not cells.
• A detail row's expand button names the row it opens with aria-controls; a tree's Expand all button carries aria-expanded.
• A row handle (rowReorder) is a button that lifts with Space; moves and drops are announced.
• The fill handle is a pointer shortcut; Ctrl+D and Ctrl+R fill from the keyboard, and fills and merges are announced.
• The value bar's input is labelled Cell value, and the active cell's name is an output labelled Active range.
• Markdown cells escape every character before adding marks; a link keeps its href only for http, https, mailto, a path or a fragment.
• Filter groups are role=group, labelled Filter group, and each group's join select is labelled Combine group filters with.

See also

• VirtualList (opens in a new tab): A long list, or a grid of rows and columns, that renders only the items near the viewport, with measured row heights.