# DataTable

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

```ehtml 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](../virtual-list): A long list, or a grid of rows and columns, that renders only the items near the viewport, with measured row heights.