ki-table
@kimen/elements/ki-table- Source
- Agent reference
Use ki-table when people compare records across columns. Use CSS grid for layout,
ki-list for single-line items, and a description list for key–value details.
| Name | Runs |
|---|---|
| Billing API | 64 |
| Search index | 18 |
<ki-table selectable sticky-header style="max-block-size: 12rem"><table> <caption>Services</caption> <thead> <tr><th scope="col">Name</th><th scope="col" data-numeric>Runs</th></tr> </thead> <tbody> <tr data-key="billing"><th scope="row">Billing API</th><td data-numeric>64</td></tr> <tr data-key="search"><th scope="row">Search index</th><td data-numeric>18</td></tr> </tbody></table></ki-table>Author the table
Give the native table a caption, add scope="col" to the column headers,
and make the first data cell in each row a th scope="row". Put numeric
headers and values at the inline end with data-numeric. Use data-meta
for secondary cell text. Use ki-badge size="sm" for a status or
ki-avatar size="xs" alongside the person’s name.
Add data-sort with a column key to a header to make a sort button. A header
with rich content can supply its own direct button type="button". Listen for
ki-sort, sort the rows, and set aria-sort only on the active column.
Set selectable and give each selectable row a stable, distinct data-key.
With individual imports or a framework wrapper, register ki-checkbox from
@kimen/elements/ki-checkbox. The full loader registers both elements.
ki-selection-change reports the checked keys in displayed order. Translate
select-all-label and row-selection-label for the page language. Include
{row} in the row label where the row name should appear.
To add row actions, put a labelled ki-icon-button size="xs" variant="ghost"
in a trailing cell and point ki-menu at the trigger’s ID with anchor. Give the column
an accessible header such as “Actions”. The table keeps every column
available in its scroll frame. Set a maximum block size for a sticky header.
The host application supplies native table markup. The catalog entry describes the content and events, and the guarded renderer currently accepts only its allowlisted elements.
API reference
When to use: Show records with shared fields that people compare, scan or sort. Supply a native caption, column headers with scope="col" and record headers with scope="row". Mark numeric cells with data-numeric and secondary cells with data-meta. The host application supplies the native table markup.
When not to use: Lay out a screen, show a short one-line list, or present the name-value details of one record. Use CSS grid, ki-list or a description list.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
density | density | "compact" | "default" | 'default' | Row density. Default measures 48px and compact measures 40px at a 16px root on desktop. |
loading | loading | boolean | false | Makes the native table busy and adds a decorative loading row after the current records. |
row-selection-label | rowSelectionLabel | string | 'Select {row}' | Accessible name template for each row checkbox. Include {row} for the row header or key. |
select-all-label | selectAllLabel | string | 'Select all rows' | Accessible name for the bulk selection checkbox. Translate for the page language. |
selectable | selectable | boolean | false | Adds a leading selection column with a checked, mixed or unchecked bulk control. Give each selectable body row a distinct, nonempty data-key. Register ki-checkbox alongside ki-table when using individual component imports. |
sticky-header | stickyHeader | boolean | false | Keeps the native column header in view inside a vertically constrained frame. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-selection-change | CustomEvent<KiTableSelectionDetail> | A person changes selection with a checkbox. The event supplies the selected data-key values in displayed order. |
ki-sort | CustomEvent<KiTableSortDetail> | A person activates a sortable column. Use the key and direction to sort records and move aria-sort to the active header. The event is a request. |
Slots
| Slot | Description |
|---|---|
| (default) | One native light-DOM table with a caption, head and body. Use data-sort on sortable headers and data-key on each record available for selection. |
CSS custom properties
The public styling contract of ki-table: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-density-control-offset | Added to the block size of every scaled control and row (button, icon button, field, select, textarea, option, list item, tab). Components floor the result at ki.size.target-min. |
--ki-density-target-min | The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). |
--ki-table-backdrop-filter | Complete filter applied behind the frame. |
--ki-table-bg | Table frame and caption surface. |
--ki-table-bg-image | Optional image layered over the table frame. |
--ki-table-border | Frame and row dividers. |
--ki-table-border-width | Frame and row divider stroke. |
--ki-table-caption-font-family | Typeface of the native table caption. |
--ki-table-cell-padding-inline | Horizontal space inside cells. |
--ki-table-fg | Primary record and caption ink. |
--ki-table-focus-radius | Corner radius of the sort button focus ring. |
--ki-table-focus-ring-color | Keyboard focus outline ink. |
--ki-table-focus-ring-offset | Space between a focus outline and its control. |
--ki-table-focus-ring-width | Keyboard focus outline stroke. |
--ki-table-header-bg | Column header surface, including when sticky. |
--ki-table-header-bg-image | Optional image layered over the column header. |
--ki-table-header-fg | Column header ink. |
--ki-table-header-height | Column header row height. |
--ki-table-meta-fg | Secondary and numeric value ink. |
--ki-table-radius | Outer frame corner radius. |
--ki-table-row-height | Default data row height. |
--ki-table-row-height-compact | Compact data row height. |
--ki-table-row-hover-bg | Surface under a record on hover. |
--ki-table-row-hover-fg | Record ink on hover. |
--ki-table-row-selected-bg | Surface under a selected record. |
--ki-table-row-selected-fg | Record ink when selected. |
--ki-table-skeleton | Decorative loading bar fill. |
--ki-table-skeleton-height | Loading bar height. |
--ki-table-skeleton-radius | Loading bar corner radius. |
--ki-table-sort-gap | Space between a column label and sort indicator. |
--ki-table-sort-glyph-size | Decorative sort indicator edge. |
--ki-table-touch-target-min | Minimum width and height of controls with a coarse pointer. |
--ki-typography-family-body | semantic font family for typography family body. |
--ki-typography-line-height-body-1 | semantic dimension for typography line height body 1. |
--ki-typography-line-height-caption-2 | semantic dimension for typography line height caption 2. |
--ki-typography-size-body-1 | semantic dimension for typography size body 1. |
--ki-typography-size-caption-2 | semantic dimension for typography size caption 2. |
--ki-typography-visually-hidden-size | Nonzero edge for clipped text available to assistive technology. |
--ki-typography-weight-body-medium | semantic font weight for typography weight body medium. |
--ki-typography-weight-body-semibold | semantic font weight for typography weight body semibold. |