Skip to content
Kimenpre-v1documentation home
Color scheme

ki-table

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.

Theme for this example
Color scheme for this example
Services
NameRuns
Billing API64
Search index18
<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

AttributePropertyTypeDefaultDescription
densitydensity"compact" | "default"'default'Row density. Default measures 48px and compact measures 40px at a 16px root on desktop.
loadingloadingbooleanfalseMakes the native table busy and adds a decorative loading row after the current records.
row-selection-labelrowSelectionLabelstring'Select {row}'Accessible name template for each row checkbox. Include {row} for the row header or key.
select-all-labelselectAllLabelstring'Select all rows'Accessible name for the bulk selection checkbox. Translate for the page language.
selectableselectablebooleanfalseAdds 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-headerstickyHeaderbooleanfalseKeeps the native column header in view inside a vertically constrained frame.

Events

EventDetail typeDescription
ki-selection-changeCustomEvent<KiTableSelectionDetail>A person changes selection with a checkbox. The event supplies the selected data-key values in displayed order.
ki-sortCustomEvent<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

SlotDescription
(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.

TokenDescription
--ki-density-control-offsetAdded 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-minThe 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-filterComplete filter applied behind the frame.
--ki-table-bgTable frame and caption surface.
--ki-table-bg-imageOptional image layered over the table frame.
--ki-table-borderFrame and row dividers.
--ki-table-border-widthFrame and row divider stroke.
--ki-table-caption-font-familyTypeface of the native table caption.
--ki-table-cell-padding-inlineHorizontal space inside cells.
--ki-table-fgPrimary record and caption ink.
--ki-table-focus-radiusCorner radius of the sort button focus ring.
--ki-table-focus-ring-colorKeyboard focus outline ink.
--ki-table-focus-ring-offsetSpace between a focus outline and its control.
--ki-table-focus-ring-widthKeyboard focus outline stroke.
--ki-table-header-bgColumn header surface, including when sticky.
--ki-table-header-bg-imageOptional image layered over the column header.
--ki-table-header-fgColumn header ink.
--ki-table-header-heightColumn header row height.
--ki-table-meta-fgSecondary and numeric value ink.
--ki-table-radiusOuter frame corner radius.
--ki-table-row-heightDefault data row height.
--ki-table-row-height-compactCompact data row height.
--ki-table-row-hover-bgSurface under a record on hover.
--ki-table-row-hover-fgRecord ink on hover.
--ki-table-row-selected-bgSurface under a selected record.
--ki-table-row-selected-fgRecord ink when selected.
--ki-table-skeletonDecorative loading bar fill.
--ki-table-skeleton-heightLoading bar height.
--ki-table-skeleton-radiusLoading bar corner radius.
--ki-table-sort-gapSpace between a column label and sort indicator.
--ki-table-sort-glyph-sizeDecorative sort indicator edge.
--ki-table-touch-target-minMinimum width and height of controls with a coarse pointer.
--ki-typography-family-bodysemantic font family for typography family body.
--ki-typography-line-height-body-1semantic dimension for typography line height body 1.
--ki-typography-line-height-caption-2semantic dimension for typography line height caption 2.
--ki-typography-size-body-1semantic dimension for typography size body 1.
--ki-typography-size-caption-2semantic dimension for typography size caption 2.
--ki-typography-visually-hidden-sizeNonzero edge for clipped text available to assistive technology.
--ki-typography-weight-body-mediumsemantic font weight for typography weight body medium.
--ki-typography-weight-body-semiboldsemantic font weight for typography weight body semibold.

Workshop

Open ki-table in Storybook