ki-tabs
@kimen/elements/ki-tabs- Source
- Agent reference
A tab group for switching between small sets of peer views inside the same
page, with one visible panel at a time. Tabs pair with panels through a
shared value; the group’s value selects the active pair and label
names the tablist.
<ki-tabs label="Settings" value="email"><ki-tab value="email">Email</ki-tab><ki-tab value="security">Security</ki-tab><ki-tab-panel value="email">Email delivery preferences</ki-tab-panel><ki-tab-panel value="security">Security and sign-in preferences</ki-tab-panel></ki-tabs>Examples
Section titled “Examples”Variants and icons
Section titled “Variants and icons”Use one primary group per screen. Use secondary tabs for sections inside a
view. Secondary tabs have a full-width indicator and put icons inline by
default. Primary tabs stack icons above the label. Set icon-layout to
stacked or inline to override the group layout.
<ki-tabs label="Mail sections" variant="secondary"><ki-tab value="inbox"> <svg slot="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"> <path d="M3 5h18v14H3zM3 5l9 7 9-7" /> </svg> Inbox</ki-tab><ki-tab value="sent">Sent</ki-tab><ki-tab-panel value="inbox">Incoming messages</ki-tab-panel><ki-tab-panel value="sent">Sent messages</ki-tab-panel></ki-tabs>Keep a visible text label in every tab. The SVG in slot="icon" is
decorative, and the text names the tab and its panel.
Disabled tabs
Section titled “Disabled tabs”A disabled tab stays visible but cannot be selected by any modality:
<ki-tabs label="Billing" value="plans"><ki-tab value="plans">Plans</ki-tab><ki-tab value="invoices" disabled>Invoices</ki-tab><ki-tab-panel value="plans">Plan management</ki-tab-panel><ki-tab-panel value="invoices">Invoice history</ki-tab-panel></ki-tabs>The change event
Section titled “The change event”User selection dispatches a composed ki-change event carrying the new
value in detail.value; programmatic value writes stay silent:
const tabs = document.querySelector('ki-tabs');
tabs?.addEventListener('ki-change', (event) => { console.log((event as CustomEvent<{ value: string }>).detail.value);});API reference
Section titled “API reference”When to use: switch between small sets of peer views inside the same page, with one visible panel at a time. Use primary for the screen-level group and secondary inside content.
When not to use: selecting form values (use ki-radio-group), page navigation (use links), step flows, or standalone ki-tab / ki-tab-panel children outside this group.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
icon-layout | iconLayout | "inline" | "stacked" | undefined | – | Positions the decorative icon relative to its tab label. When omitted, primary stacks the icon above the label and secondary puts it inline. |
label | label | string | undefined | – | Accessible name for the tablist. Always provide one when multiple tab groups may appear in a view. When NOT to use: do not use label as a visible heading; render visible context in surrounding content. |
size | size | "lg" | "md" | "sm" | "xl" | "xs" | 'md' | Token-backed strip size: every ki-tab it holds is 24, 32, 40, 48 or 56px tall in onmars, with its text, and the gap between tabs follows. The strip decides for all its tabs; a tab has no size of its own. An unrecognized value matches no style rule and keeps the medium metrics. When to use: match the size of the controls around the strip. When NOT to use: do not pick a smaller size to fit a dense region or a larger one for touch; declare data-ki-density on the region instead, which composes with every size. |
value | value | string | '' | Resolved selected value. The attribute declares the initial request; the live property falls back to the first enabled owner tab, or "" when no tab is selectable. Programmatic writes are silent. |
variant | variant | "primary" | "secondary" | undefined | 'primary' | Visual treatment for the group. Use one primary group per screen and secondary groups within content. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-change | CustomEvent<{ value: string }> | Fired once after a user-driven selection change from pointer or keyboard navigation. detail.value is the resolved selected value and value is already current when listeners run. Programmatic value writes and first-render fallback are silent. |
Slots
| Slot | Description |
|---|---|
| (default) | ki-tab and ki-tab-panel children. Tabs are auto-assigned to an internal named slot as managed output. |
CSS parts
| Part | Description |
|---|---|
tablist | Internal row around the tab strip: gap, alignment and the divider. The strip inside it carries the tablist role. |
CSS custom properties
The public styling contract of ki-tabs: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-tab-icon-stacked-gap | Gap from a stacked tab icon to its label. |
--ki-tab-icon-stacked-min-block-size | Minimum block size for a tab with a stacked icon. |
--ki-tab-lg-font-size | dimension used by the tab component for lg font size (Tab-nav-item 10048:1068 lg: UI/body-2). |
--ki-tab-lg-line-height | dimension used by the tab component for lg line height (Tab-nav-item 10048:1068 lg: UI/body-2). |
--ki-tab-lg-min-block-size | dimension used by the tab component for lg min block size (Tab-nav-item 10048:1068 lg: 48px). |
--ki-tab-padding-block-end | dimension used by the tab component for padding block end (MarsUI Tab_nav_item: 8px inset keeping the 2px underline clear of the 13/24 label; formalizes the fallback ki-tab.css already consumes). |
--ki-tab-primary-indicator-height | Height of the content-width indicator on a primary icon tab. |
--ki-tab-secondary-indicator-height | Height of the full-width indicator on a secondary tab. |
--ki-tab-sm-font-size | dimension used by the tab component for sm font size (Tab-nav-item 10048:1068 sm: UI/para). |
--ki-tab-sm-line-height | dimension used by the tab component for sm line height (Tab-nav-item 10048:1068 sm: UI/para). |
--ki-tab-sm-min-block-size | dimension used by the tab component for sm min block size (Tab-nav-item 10048:1068 sm: 32px). |
--ki-tab-xl-font-size | dimension used by the tab component for xl font size (Tab-nav-item 10048:1068 xl: UI/title-2). |
--ki-tab-xl-line-height | dimension used by the tab component for xl line height (Tab-nav-item 10048:1068 xl: UI/title-2). |
--ki-tab-xl-min-block-size | dimension used by the tab component for xl min block size (Tab-nav-item 10048:1068 xl: 56px). |
--ki-tab-xs-font-size | dimension used by the tab component for xs font size (Tab-nav-item 10048:1068 xs: UI/caption-2). Figma draws caption_1, 10px; caption_2, 12px, is the smallest text the library ships (spec 050 D7). |
--ki-tab-xs-line-height | dimension used by the tab component for xs line height (Tab-nav-item 10048:1068 xs: UI/caption-2). |
--ki-tab-xs-min-block-size | dimension used by the tab component for xs min block size (Tab-nav-item 10048:1068 xs: 24px). |
--ki-tabs-divider-color | color used by the tabs component for divider color. |
--ki-tabs-divider-width | dimension used by the tabs component for the tablist divider width (the Tab_nav bar has no stroke; the hook stays for consumers to opt back in — material3 keeps its hairline via its override). |
--ki-tabs-gap | dimension used by the tabs component for gap (MarsUI md bar item gap Space/8xl 26px; the gap carries all spacing now that items have zero inline padding). |
--ki-tabs-lg-gap | dimension used by the tabs component for the lg gap between tabs (Tab-nav 10048:1249 lg binds Space/9xl, 28px). |
--ki-tabs-secondary-selected-rest-bg | Selected secondary tab background at rest. |
--ki-tabs-secondary-selected-rest-fg | Selected secondary tab label foreground at rest. |
--ki-tabs-secondary-unselected-rest-bg | Secondary tab background at rest. |
--ki-tabs-secondary-unselected-rest-fg | Secondary tab label foreground at rest. |
--ki-tabs-sm-gap | dimension used by the tabs component for the sm gap between tabs (Tab-nav 10048:1249 sm binds Space/7xl, 24px). |
--ki-tabs-xl-gap | dimension used by the tabs component for the xl gap between tabs (Tab-nav 10048:1249 xl binds Space/10xl, 32px). |
--ki-tabs-xs-gap | dimension used by the tabs component for the xs gap between tabs (Tab-nav 10048:1249 xs binds Space/5xl, 20px). |
--ki-typography-family-body | semantic font family for typography family body. |
When to use: label one peer content view inside ki-tabs, with optional decorative icon and start or end slot media.
When not to use: standalone, for form value selection, or for page navigation; use the parent group's value instead of authoring selected.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
disabled | disabled | boolean | false | Prevents selection by every modality and exposes the unavailable state. Boolean presence semantics apply: disabled="false" is still disabled. |
selected | selected | boolean | false | Output-only selected state written by ki-tabs. Set the group's value to choose an initial tab; author-set selected is overwritten. |
value | value | string | '' | Pairing identifier shared with a ki-tab-panel. The first tab with a value owns it; later duplicates render but are not selectable. |
Slots
| Slot | Description |
|---|---|
| (default) | Required visible text label and accessible name source. |
end | Trailing icon or media. Follows writing direction. |
icon | Decorative SVG. Supply visible text in the default slot. |
start | Leading icon or media. Follows writing direction. |
CSS parts
| Part | Description |
|---|---|
indicator | Decorative selected-tab marker. |
tab | Tab surface. |
CSS custom properties
The public styling contract of ki-tab: 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-motion-distance-xs | Motion travel distance xs (2px): hover-lift offsets. |
--ki-motion-duration-fast | Fast interaction transition duration. |
--ki-motion-easing-out | Decelerating interaction transition easing curve. |
--ki-motion-easing-standard | Standard interaction transition easing curve. |
--ki-tab-backdrop-filter | Complete backdrop filter for a tab surface. |
--ki-tab-bg-image | Optional surface image for a tab. |
--ki-tab-focus-ring-color | color used by the tab component for focus ring color. |
--ki-tab-focus-ring-offset | dimension used by the tab component for focus ring offset. |
--ki-tab-focus-ring-shadow | shadow used by the tab component for the focus ring glow (MarsUI Focus/primary: 3px spread ring at 20% — see ki.focus.primary. specs/002-ki-button/design-extraction.md §2.5 recorded 40%, having read the alpha off the Dark canvas mode, same double mechanism as ki-button: glow plus the opaque indicator). |
--ki-tab-focus-ring-width | dimension used by the tab component for focus ring width. |
--ki-tab-font-size | dimension used by the tab component for font size. |
--ki-tab-font-weight | font weight used by the tab component for font weight. |
--ki-tab-gap | dimension used by the tab component for gap. |
--ki-tab-icon-inline-gap | Gap from an inline tab icon to its label. |
--ki-tab-icon-size | Inline and block size of a decorative tab icon. |
--ki-tab-indicator-color | color used by the tab component for indicator color (MarsUI active underline is Outline/inverse_white: black in light, white in dark — the inverse neutral, not primary). |
--ki-tab-indicator-radius | dimension used by the tab component for indicator radius (the master underline is a square-ended 2px bottom border). |
--ki-tab-indicator-size | dimension used by the tab component for indicator size. |
--ki-tab-line-height | dimension used by the tab component for line height. |
--ki-tab-min-block-size | dimension used by the tab component for min block size (MarsUI Tab_nav md bar height 40px: 24px body_1 label + 8px block-end clearance + underline; retargeted from ki.space.7xl per the fidelity audit — material3 pins its own value). |
--ki-tab-padding-block-end | dimension used by the tab component for padding block end (MarsUI Tab_nav_item: 8px inset keeping the 2px underline clear of the 13/24 label; formalizes the fallback ki-tab.css already consumes). |
--ki-tab-padding-inline | dimension used by the tab component for padding inline (MarsUI items carry no inline padding: spacing comes from the bar gap and the underline spans the full item width). |
--ki-tab-radius | dimension used by the tab component for radius. |
--ki-tab-selected-active-bg | color used by the tab component for selected active background (MarsUI Tab_nav is transparent_inverse in every state; background pills are Switcher language). |
--ki-tab-selected-active-fg | color used by the tab component for selected active foreground (MarsUI active tab label is neutral Text/high_em — never purple; master 10048:1240). |
--ki-tab-selected-disabled-bg | color used by the tab component for selected disabled background (no disabled variant exists in Tab_nav; disabled must be quieter than rest, not a filled pill). |
--ki-tab-selected-disabled-fg | color used by the tab component for selected disabled foreground (MarsUI disabled ladder: Gray/500 light / White-32 dark, the value ki-status and ki-switch already use for disabled glyphs). |
--ki-tab-selected-hover-bg | color used by the tab component for selected hover background (MarsUI Tab_nav is transparent_inverse in every state; background pills are Switcher language). |
--ki-tab-selected-hover-fg | color used by the tab component for selected hover foreground (MarsUI active tab label is neutral Text/high_em — never purple; master 10048:1240). |
--ki-tab-selected-rest-bg | color used by the tab component for selected rest background (MarsUI Tab_nav is transparent_inverse in every state; background pills are Switcher language). |
--ki-tab-selected-rest-fg | color used by the tab component for selected rest foreground (MarsUI active tab label is neutral Text/high_em — never purple; master 10048:1240). |
--ki-tab-unselected-active-bg | color used by the tab component for unselected active background (MarsUI Tab_nav is transparent_inverse in every state). |
--ki-tab-unselected-active-fg | color used by the tab component for unselected active foreground (mirrors hover; MarsUI defines no pressed variant). |
--ki-tab-unselected-disabled-bg | color used by the tab component for unselected disabled background (no disabled variant exists in Tab_nav; disabled must be quieter than rest, not a filled pill). |
--ki-tab-unselected-disabled-fg | color used by the tab component for unselected disabled foreground (MarsUI disabled ladder: Gray/500 light / White-32 dark, the value ki-status and ki-switch already use for disabled glyphs). |
--ki-tab-unselected-hover-bg | color used by the tab component for unselected hover background (MarsUI Tab_nav is transparent_inverse in every state). |
--ki-tab-unselected-hover-fg | color used by the tab component for unselected hover foreground (with rest at med_em, hover darkens one em step, preserving the master rest-to-hover direction). |
--ki-tab-unselected-rest-bg | color used by the tab component for unselected rest background (MarsUI Tab_nav is transparent_inverse in every state). |
--ki-tab-unselected-rest-fg | color used by the tab component for unselected rest foreground (Figma inactive is Text/low_em, which fails the 4.5:1 text gate at 13px; med_em is the gate-compliant rest value — declared deviation). |
--ki-typography-family-body | semantic font family for typography family body. |
Accessibility
Section titled “Accessibility”label names the tablist, as the APG tabs pattern requires. Selection
follows the pattern: the tablist is one tab stop and arrow keys move
between tabs. Tabs are for peer views inside a page — for page navigation
use links, for form values use
ki-radio-group.