# A data table: records in rows and columns, compared by scanning down a column. It wraps a native and gives it the system's styles, sortable columns, and a scroll box the keyboard can reach when the table is too wide for the screen. Use it for records people compare (invoices, members, deployments); use aihio-grid of cards for a few summaries, and never a table for layout. For more rows than a page can hold, show one page at a time with aihio-pagination, or use aihio-data-grid. Intents: `tabular-data`. ## Attributes - `density` (`default` | `compact`): Row spacing. compact fits more rows on screen, for dense data that people scan. Default: `default`. - `sticky-header` (boolean): Keeps the header in view while the rows scroll. The table scrolls inside its own box, which grows to --aihio-table-max-height (min(32rem, 75dvh) unless you set it) before its rows scroll. Default: `false`. - `manual-sort` (boolean): Leaves the order of the rows to your code. A click on a sortable header still marks it with aria-sort, announces it, and fires aihio-sort, but the rows stay as rendered: sort them yourself, as a framework re-rendering from state or a request to the server does. Without it the table reorders its own rows. Default: `false`. - `loading` (boolean): Marks the rows as stale while new ones load, such as after a sort sent to the server: they are dimmed, and the table has aria-busy. Default: `false`. - `sort-ascending-text` (string): Announced after sorting a column ascending, with {column} for the header's text. For localisation (e.g. "Lajiteltu: {column}, nouseva"). Default: `Sorted by {column}, ascending`. - `sort-descending-text` (string): Announced after sorting a column descending, with {column} for the header's text. Default: `Sorted by {column}, descending`. ## Properties - `table` (`HTMLTableElement | null`, read-only): The
the element enhances. ## Methods - `sort()`: Sorts by the column whose data-sortable value, or header text, is column: ascending unless direction says otherwise. It moves aria-sort to that header and, without manual-sort, reorders the rows. Like a value set from script, it fires no aihio-sort and announces nothing. ## Events - `aihio-sort` (detail: column: string, direction: 'ascending' | 'descending'): Fired when the person sorts by a column, once its header carries the new aria-sort and, without manual-sort, the rows are in their new order. column is the header's data-sortable value, or its text when that is empty. Not fired by sort(). ## Native elements reads these attributes on the native elements inside it. ### it names a column; in a body row, with scope="row", it names the row. #### . - `aria-sort` (`ascending` | `descending` | `none` | `other`): The order the rows are in. Write it on the header the rows are sorted by when the page loads; without manual-sort the table puts the rows in that order. The table moves it from header to header as people sort. - `data-numeric` (boolean): Lines a column of figures up by place value: end-aligned, in tabular digits. Put it on the column's header and on each of its cells. Default: `false`. - `data-sort-value` (string): What a row header sorts by, when its text does not sort the way it reads. See row, and each row with , and the cell that names each row is a holds the totals. ```html
A header cell. In
attributes - `data-sortable` (string): Makes the column sortable: the header's content becomes a button that sorts the rows by it, ascending first and then descending. The value names the column for aihio-sort and sort(), and can be left empty when nothing reads it. Only on a in
. ### A data cell. #### attributes - `data-sort-value` (string): What the cell sorts by when its text does not sort the way it reads, such as a priority ("High" before "Low") or a date written out. A . Default: `false`. ## Accessibility obligations - (error, table-accessible-name) When the table has no caption, aria-label, or aria-labelledby: Name the table: a
as its first child, aria-labelledby pointing at the visible heading above it, or aria-label. An unnamed table is announced only as "table", and so is the scroll box it gets on a narrow screen. - (error, table-header-cells) When the table has no
cells: Name each column with a in a
where one cell identifies it. Bold text in an ordinary cell is not a header. - (error, table-click-handler) When a row, header, or cell responds to clicks and holds no link or button: Sort with data-sortable on the , and put a link or button in the row for anything else, such as a link in the cell that names it. A click handler on a row or cell is reachable by pointer only. - (warn, table-sort-column-name) When manual-sort is set and a sortable header has no column name: Give each sortable header a name, data-sortable="amount", so aihio-sort says which column to sort by without depending on the header's wording. ## Examples ### Records with a caption Each column is named by a in
. data-numeric lines figures up by place value, and a
Invoices
Invoice Customer Status Amount
INV-1042 Northwind Traders Paid €1,250.00
INV-1043 Fabrikam Due €980.50
INV-1044 Contoso Overdue €12,400.00
Total €14,630.50
``` ### Sortable columns data-sortable makes a header a sort button. The rows load sorted by the header with aria-sort. A