Skip to content
Kimenpre-v1documentation home
Color scheme

ki-segmented-control

Use a segmented control for a small set of choices that take effect immediately, such as a chart range or view mode. Use ki-tabs for content panels, ki-radio-group for form submission and ki-select for longer lists.

Theme for this example
Color scheme for this example
Day Week Month
<ki-segmented-control label="Chart range" value="week">
<ki-segment value="day">Day</ki-segment>
<ki-segment value="week">Week</ki-segment>
<ki-segment value="month">Month</ki-segment>
</ki-segmented-control>

Supply a group label and a distinct value for each direct ki-segment child. Set the group’s value to select an option, or omit it to start on the first enabled choice. Listen to ki-change for user changes. The new selection is in event.detail.value.

Tab enters on the selected option. Arrow keys move focus and selection, wrapping around and skipping unavailable options. Give an icon-only option an aria-label for its name and tooltip.

The xs, sm and md tracks default to 28, 32 and 40 CSS px. Add full-width to distribute the row evenly. Inside a region with data-ki-density="touch", each option grows to the touch-target minimum.

The all-elements loader registers ki-tooltip. When using direct imports or framework wrappers, register it separately for icon-only options.

API reference

When to use: apply a chart range, view mode, or another immediate setting.

When not to use: switching between panels (ki-tabs), submitted form choices (ki-radio-group), or more than five options (ki-select).

Properties & attributes

AttributePropertyTypeDefaultDescription
full-widthfullWidthbooleanfalseDistribute the available inline space evenly among all segments.
labellabelstring–Required accessible name of the group. Use a short name for the setting.
sizesize"md" | "sm" | "xs"'md'Track size. The default heights are 28, 32 and 40 CSS px respectively; surrounding density settings can increase or decrease targets.
valuevaluestring''Resolved selected value. Set it to choose an option programmatically. Omit it to select the first available option. The value is empty when there are no available options. Programmatic changes are silent.

Events

EventDetail typeDescription
ki-changeCustomEvent<{ value: string }>Emitted once per changed user choice with the new resolved value.

Slots

SlotDescription
(default)Two to five direct ki-segment children with distinct nonempty values.

CSS parts

PartDescription
trackSurface containing the radiogroup and its options.

CSS custom properties

The public styling contract of ki-segmented-control: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-density-space-scaleMultiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip).
--ki-segment-font-size-xsText size of extra-small segments.
--ki-segment-line-height-xsLine height of extra-small segments.
--ki-segment-padding-inline-xsInline padding of an extra-small segment.
--ki-segmented-control-track-size-mdMedium track height before density adjustment.
--ki-segmented-control-track-size-smSmall track height before density adjustment.
--ki-segmented-control-track-size-xsExtra-small track height before density adjustment.
--ki-segmented-radiusCorner radius of the control track.
--ki-segmented-track-backdrop-filterComplete CSS backdrop filter behind the track.
--ki-segmented-track-bgSolid surface for the segment track.
--ki-segmented-track-bg-imageOptional image layered over the track surface.
--ki-segmented-track-gapGap between adjacent segments.
--ki-segmented-track-paddingInset between the track and its segments.
--ki-typography-family-bodysemantic font family for typography family body.

Open ki-segmented-control in Storybook