Skip to content
Kimenpre-v1documentation home
Color scheme

ki-tabs

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.

Theme for this example
Color scheme for this example
Email Security Email delivery preferences Security and sign-in preferences
<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>

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.

Theme for this example
Color scheme for this example
Inbox Sent Incoming messages Sent messages
<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.

A disabled tab stays visible but cannot be selected by any modality:

Theme for this example
Color scheme for this example
Plans Invoices Plan management Invoice history
<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>

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);
});

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

AttributePropertyTypeDefaultDescription
icon-layouticonLayout"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.
labellabelstring | 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.
sizesize"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.
valuevaluestring''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.
variantvariant"primary" | "secondary" | undefined'primary'Visual treatment for the group. Use one primary group per screen and secondary groups within content.

Events

EventDetail typeDescription
ki-changeCustomEvent<{ 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

SlotDescription
(default)ki-tab and ki-tab-panel children. Tabs are auto-assigned to an internal named slot as managed output.

CSS parts

PartDescription
tablistInternal 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.

TokenDescription
--ki-tab-icon-stacked-gapGap from a stacked tab icon to its label.
--ki-tab-icon-stacked-min-block-sizeMinimum block size for a tab with a stacked icon.
--ki-tab-lg-font-sizedimension used by the tab component for lg font size (Tab-nav-item 10048:1068 lg: UI/body-2).
--ki-tab-lg-line-heightdimension used by the tab component for lg line height (Tab-nav-item 10048:1068 lg: UI/body-2).
--ki-tab-lg-min-block-sizedimension used by the tab component for lg min block size (Tab-nav-item 10048:1068 lg: 48px).
--ki-tab-padding-block-enddimension 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-heightHeight of the content-width indicator on a primary icon tab.
--ki-tab-secondary-indicator-heightHeight of the full-width indicator on a secondary tab.
--ki-tab-sm-font-sizedimension used by the tab component for sm font size (Tab-nav-item 10048:1068 sm: UI/para).
--ki-tab-sm-line-heightdimension used by the tab component for sm line height (Tab-nav-item 10048:1068 sm: UI/para).
--ki-tab-sm-min-block-sizedimension used by the tab component for sm min block size (Tab-nav-item 10048:1068 sm: 32px).
--ki-tab-xl-font-sizedimension used by the tab component for xl font size (Tab-nav-item 10048:1068 xl: UI/title-2).
--ki-tab-xl-line-heightdimension used by the tab component for xl line height (Tab-nav-item 10048:1068 xl: UI/title-2).
--ki-tab-xl-min-block-sizedimension used by the tab component for xl min block size (Tab-nav-item 10048:1068 xl: 56px).
--ki-tab-xs-font-sizedimension 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-heightdimension used by the tab component for xs line height (Tab-nav-item 10048:1068 xs: UI/caption-2).
--ki-tab-xs-min-block-sizedimension used by the tab component for xs min block size (Tab-nav-item 10048:1068 xs: 24px).
--ki-tabs-divider-colorcolor used by the tabs component for divider color.
--ki-tabs-divider-widthdimension 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-gapdimension 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-gapdimension 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-bgSelected secondary tab background at rest.
--ki-tabs-secondary-selected-rest-fgSelected secondary tab label foreground at rest.
--ki-tabs-secondary-unselected-rest-bgSecondary tab background at rest.
--ki-tabs-secondary-unselected-rest-fgSecondary tab label foreground at rest.
--ki-tabs-sm-gapdimension used by the tabs component for the sm gap between tabs (Tab-nav 10048:1249 sm binds Space/7xl, 24px).
--ki-tabs-xl-gapdimension used by the tabs component for the xl gap between tabs (Tab-nav 10048:1249 xl binds Space/10xl, 32px).
--ki-tabs-xs-gapdimension used by the tabs component for the xs gap between tabs (Tab-nav 10048:1249 xs binds Space/5xl, 20px).
--ki-typography-family-bodysemantic 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

AttributePropertyTypeDefaultDescription
disableddisabledbooleanfalsePrevents selection by every modality and exposes the unavailable state. Boolean presence semantics apply: disabled="false" is still disabled.
selectedselectedbooleanfalseOutput-only selected state written by ki-tabs. Set the group's value to choose an initial tab; author-set selected is overwritten.
valuevaluestring''Pairing identifier shared with a ki-tab-panel. The first tab with a value owns it; later duplicates render but are not selectable.

Slots

SlotDescription
(default)Required visible text label and accessible name source.
endTrailing icon or media. Follows writing direction.
iconDecorative SVG. Supply visible text in the default slot.
startLeading icon or media. Follows writing direction.

CSS parts

PartDescription
indicatorDecorative selected-tab marker.
tabTab surface.

CSS custom properties

The public styling contract of ki-tab: 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-motion-distance-xsMotion travel distance xs (2px): hover-lift offsets.
--ki-motion-duration-fastFast interaction transition duration.
--ki-motion-easing-outDecelerating interaction transition easing curve.
--ki-motion-easing-standardStandard interaction transition easing curve.
--ki-tab-backdrop-filterComplete backdrop filter for a tab surface.
--ki-tab-bg-imageOptional surface image for a tab.
--ki-tab-focus-ring-colorcolor used by the tab component for focus ring color.
--ki-tab-focus-ring-offsetdimension used by the tab component for focus ring offset.
--ki-tab-focus-ring-shadowshadow 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-widthdimension used by the tab component for focus ring width.
--ki-tab-font-sizedimension used by the tab component for font size.
--ki-tab-font-weightfont weight used by the tab component for font weight.
--ki-tab-gapdimension used by the tab component for gap.
--ki-tab-icon-inline-gapGap from an inline tab icon to its label.
--ki-tab-icon-sizeInline and block size of a decorative tab icon.
--ki-tab-indicator-colorcolor 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-radiusdimension used by the tab component for indicator radius (the master underline is a square-ended 2px bottom border).
--ki-tab-indicator-sizedimension used by the tab component for indicator size.
--ki-tab-line-heightdimension used by the tab component for line height.
--ki-tab-min-block-sizedimension 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-enddimension 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-inlinedimension 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-radiusdimension used by the tab component for radius.
--ki-tab-selected-active-bgcolor 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-fgcolor 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-bgcolor 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-fgcolor 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-bgcolor 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-fgcolor 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-bgcolor 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-fgcolor 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-bgcolor used by the tab component for unselected active background (MarsUI Tab_nav is transparent_inverse in every state).
--ki-tab-unselected-active-fgcolor used by the tab component for unselected active foreground (mirrors hover; MarsUI defines no pressed variant).
--ki-tab-unselected-disabled-bgcolor 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-fgcolor 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-bgcolor used by the tab component for unselected hover background (MarsUI Tab_nav is transparent_inverse in every state).
--ki-tab-unselected-hover-fgcolor 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-bgcolor used by the tab component for unselected rest background (MarsUI Tab_nav is transparent_inverse in every state).
--ki-tab-unselected-rest-fgcolor 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-bodysemantic font family for typography family body.

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.

Open ki-tabs in Storybook