ki-segmented-control
@kimen/elements/ki-segmented-control- Source
- Agent reference
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.
<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
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
full-width | fullWidth | boolean | false | Distribute the available inline space evenly among all segments. |
label | label | string | – | Required accessible name of the group. Use a short name for the setting. |
size | size | "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. |
value | value | string | '' | 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
| Event | Detail type | Description |
|---|---|---|
ki-change | CustomEvent<{ value: string }> | Emitted once per changed user choice with the new resolved value. |
Slots
| Slot | Description |
|---|---|
| (default) | Two to five direct ki-segment children with distinct nonempty values. |
CSS parts
| Part | Description |
|---|---|
track | Surface 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.
| Token | Description |
|---|---|
--ki-density-space-scale | Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). |
--ki-segment-font-size-xs | Text size of extra-small segments. |
--ki-segment-line-height-xs | Line height of extra-small segments. |
--ki-segment-padding-inline-xs | Inline padding of an extra-small segment. |
--ki-segmented-control-track-size-md | Medium track height before density adjustment. |
--ki-segmented-control-track-size-sm | Small track height before density adjustment. |
--ki-segmented-control-track-size-xs | Extra-small track height before density adjustment. |
--ki-segmented-radius | Corner radius of the control track. |
--ki-segmented-track-backdrop-filter | Complete CSS backdrop filter behind the track. |
--ki-segmented-track-bg | Solid surface for the segment track. |
--ki-segmented-track-bg-image | Optional image layered over the track surface. |
--ki-segmented-track-gap | Gap between adjacent segments. |
--ki-segmented-track-padding | Inset between the track and its segments. |
--ki-typography-family-body | semantic font family for typography family body. |