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.

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>

Examples

Disabled tabs

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

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>

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

When to use: switch between small sets of peer views inside the same page, with one visible panel at a time.

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

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 strip carrying 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-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-typography-family-body	semantic font family for typography family body.

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.

Workshop

Open ki-tabs in Storybook