# Data Table

Full-featured grid: sorting, filtering, tabs, inline editing, and per-cell source citations.

## Add it to an app

1. Open the app builder and find **Data Table** in the component palette.
2. Insert it into the intended region or container.
3. Set its properties in the inspector. Use a literal for a fixed value or a binding for a value supplied by the app.
4. Connect its events where the app should respond to a user gesture.
5. Preview with representative data and save after resolving validation problems.

The type name in the builder’s code view is `data_table`.

## Settings

| Setting | Accepted value | Required | Default | What it controls |
| --- | --- | --- | --- | --- |
| Columns (`columns`) | list of object | No | [] | Supports expression bindings. The listed default is inserted when adding a new component. |
| align (`columns[].align`) | "left" / "right" | No | Not specified | — |
| anchorKey (`columns[].anchorKey`) | string | No | Not specified | — |
| confidenceKey (`columns[].confidenceKey`) | string | No | Not specified | — |
| hidden (`columns[].hidden`) | boolean | No | Not specified | — |
| key (`columns[].key`) | string | Yes | Not specified | — |
| label (`columns[].label`) | string | No | Not specified | — |
| pinned (`columns[].pinned`) | boolean | No | Not specified | — |
| sortable (`columns[].sortable`) | boolean | No | Not specified | — |
| type (`columns[].type`) | "text" / "number" / "date" / "boolean" | No | Not specified | — |
| Data (`data`) | list of object | No | [] | Supports expression bindings. Rows to show; wins over windowed mode when non-empty. The listed default is inserted when adding a new component. |
| Dock ('bottom' — literal) (`dock`) | "bottom" | No | Not specified | Literal only; do not use an expression binding. |
| Server filter payload key (`filterKey`) | string | No | Not specified | — |
| Server filter payload value (`filterValue`) | string | No | Not specified | Supports expression bindings. |
| Table height (CSS length) (`height`) | string | No | "28rem" | Supports expression bindings. The listed default is inserted when adding a new component. |
| Highlighted row (source index) (`highlightedRowIndex`) | integer or null; minimum 0 | No | Not specified | Supports expression bindings. |
| Low-confidence threshold (0..1) (`lowConfidenceBelow`) | number; minimum 0; maximum 1 | No | 0.75 | The listed default is inserted when adding a new component. |
| Open-table request (`openTableRequest`) | object or null | No | Not specified | Supports expression bindings. |
| columns (`openTableRequest.columns`) | list of object | No | Not specified | — |
| align (`openTableRequest.columns[].align`) | "left" / "right" | No | Not specified | — |
| anchorKey (`openTableRequest.columns[].anchorKey`) | string | No | Not specified | — |
| confidenceKey (`openTableRequest.columns[].confidenceKey`) | string | No | Not specified | — |
| hidden (`openTableRequest.columns[].hidden`) | boolean | No | Not specified | — |
| key (`openTableRequest.columns[].key`) | string | Yes | Not specified | — |
| label (`openTableRequest.columns[].label`) | string | No | Not specified | — |
| pinned (`openTableRequest.columns[].pinned`) | boolean | No | Not specified | — |
| sortable (`openTableRequest.columns[].sortable`) | boolean | No | Not specified | — |
| type (`openTableRequest.columns[].type`) | "text" / "number" / "date" / "boolean" | No | Not specified | — |
| id (`openTableRequest.id`) | string | Yes | Not specified | — |
| label (`openTableRequest.label`) | string | No | Not specified | — |
| revision (`openTableRequest.revision`) | number | Yes | Not specified | — |
| Populating (run in flight) (`populating`) | boolean | No | Not specified | Supports expression bindings. |
| Populating text (`populatingText`) | string | No | "Generating rows…" | The listed default is inserted when adding a new component. |
| Record type (windowed mode) (`recordType`) | string | No | "" | The listed default is inserted when adding a new component. |
| Refresh token (`refreshToken`) | string or null | No | Not specified | Supports expression bindings. A new value reloads the active table tab's rows. |
| Imperative row landing (`scrollToRow`) | integer or null; minimum 0 | No | Not specified | Supports expression bindings. Source-row index to scroll to and ring. |
| Show filter row (`showFilter`) | boolean | No | true | Supports expression bindings. The listed default is inserted when adding a new component. |
| Initial sort direction (asc\|desc) (`sortDir`) | "asc" / "desc" | No | "asc" | The listed default is inserted when adding a new component. |
| Initial sort column (`sortKey`) | string | No | Not specified | Supports expression bindings. |
| Data source id (windowed mode) (`source`) | string | No | "" | The listed default is inserted when adding a new component. |
| Tabs (`tabs`) | list of object | No | Not specified | Supports expression bindings. |
| columns (`tabs[].columns`) | list of object | No | Not specified | — |
| align (`tabs[].columns[].align`) | "left" / "right" | No | Not specified | — |
| anchorKey (`tabs[].columns[].anchorKey`) | string | No | Not specified | — |
| confidenceKey (`tabs[].columns[].confidenceKey`) | string | No | Not specified | — |
| hidden (`tabs[].columns[].hidden`) | boolean | No | Not specified | — |
| key (`tabs[].columns[].key`) | string | Yes | Not specified | — |
| label (`tabs[].columns[].label`) | string | No | Not specified | — |
| pinned (`tabs[].columns[].pinned`) | boolean | No | Not specified | — |
| sortable (`tabs[].columns[].sortable`) | boolean | No | Not specified | — |
| type (`tabs[].columns[].type`) | "text" / "number" / "date" / "boolean" | No | Not specified | — |
| data (`tabs[].data`) | list of object | No | Not specified | — |
| filterKey (`tabs[].filterKey`) | string | No | Not specified | — |
| filterValue (`tabs[].filterValue`) | string | No | Not specified | — |
| id (`tabs[].id`) | string | Yes | Not specified | — |
| label (`tabs[].label`) | string | No | Not specified | — |
| recordType (`tabs[].recordType`) | string | No | Not specified | — |
| source (`tabs[].source`) | string | No | Not specified | — |
| tableId (`tabs[].tableId`) | string | No | Not specified | — |

### Layout controls

Additional host-rendered controls: `keepMounted`. These control the surrounding component region rather than the record values.

## Values available to bindings

| Value | Type | Initial value | Meaning |
| --- | --- | --- | --- |
| `activeCitation` | object or null | null | The cited cell's anchor bag plus a monotonic revision; null when uncited. |
| `activeTabId` | string or null | null | The active tab, in tabs mode. |
| `filterActive` | boolean | false | A filter query is applied. |
| `openTabIds` | list of string | [] | Open tab ids: the authored prefix, then runtime tabs. |
| `rowsLoaded` | integer | 0 | Rows loaded so far. |
| `rowsTotal` | integer or null | null | Advisory total, when known. |
| `selectedCell` | object or null | null | The selected cell {rowIndex, columnKey, value}. |
| `selectedRow` | object or null | null | The selected row. |
| `selectedRowIndex` | integer or null | null | The selected row's source index. |
| `selectedTableCell` | object or null | null | A saved table's selected cell: table/row identity and its exact value. |
| `sortedBy` | object or null | null | The active sort {key, dir}. |
| `status` | "idle" / "loading" / "ready" / "error" / "unavailable" | "idle" | Read state of the rows. |

Refer to these values through `components.<component-id>.<value>` in a binding. Use the identifier assigned to this instance of Data Table, not the component type name.

## Events

- `onCellSelect` — A cell was selected.

- `onCite` — The active citation changed (null included).

- `onRowSelect` — A row was selected.

- `onSortChange` — The sort changed.

- `onTabChange` — Another tab became active.

- `onTabClose` — A tab was closed.

- `onTableCellChange` — The selected saved-table cell changed.

Connect only the actions the app needs. An event can fetch results, run an enabled data source, set state, update another component, show a notification, or navigate where supported.

## Keyboard and accessible labels

Accessible label source: Data table.

Updates are announced through the component’s live status region.

## Example: Bound rows with typed columns

| Setting | Example value |
| --- | --- |
| `columns` | [{"key":"url","label":"URL"},{"key":"count","label":"Count","type":"number"}] |
| `data` | "{{ dataSources.checks.data \|\| [] }}" |
| `showFilter` | true |

## Example: Tables-workbench grid docked at the bottom

| Setting | Example value |
| --- | --- |
| `dock` | "bottom" |
| `keepMounted` | true |
| `openTableRequest` | "{{ app.activeOpenRequest }}" |
| `populating` | "{{ dataSources.populate.isRunning }}" |
| `refreshToken` | "{{ dataSources.populate.lastRunAt }}" |

When `onRowSelect` occurs, the example performs:

- `setStateValue` with {"key":"viewerOpen","value":true}

## If it is empty or unavailable

Check the source binding, the selected item, and the app’s access. A hosted document, table, review, or storage component needs the corresponding app capability; an offline preview cannot supply live private data. A source running with no results is different from an invalid binding. Inspect the app’s workflow and data source before changing the presentation.