Segmented Control
Bar (text)
Toolbar — icons only
Bottom bar (mobile)
Vertical — compact (label under icon)
Vertical — icons only
The radio-group semantics laid out as a bar of segments: it chooses a value
inside a view. Beyond the default text bar it supports iconOnly (a compact
toolbar), stacked (icon over label) and orientation="vertical" (a column
of segments). The demo above shows each variant.
A Segmented Control is not navigation. A radio group announces “radio button, 2 of 5, checked” and moves the selection with the arrow keys, which is the wrong contract for moving between the sections of an application. For a bar of sections at the bottom of the screen use Navigation Bar; for side navigation use Sidebar.
Import
Section titled “Import”<script> import SegmentedControl from "@invisible-ui/svelte/SegmentedControl.svelte";</script><script setup> import { SegmentedControl } from "@invisible-ui/vue";</script>import { SegmentedControl } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-segmented-control></ds-segmented-control>In Elements, the segments come from <option> children, or from the items
property. An option’s data-icon holds the path data of a 24×24 icon. The
selection is reflected by the value attribute and reported through the
bubbling change event:
<ds-segmented-control label="View" name="view" value="list"> <option value="list">List</option> <option value="board">Board</option></ds-segmented-control>| Prop | Type | Default | Description |
|---|---|---|---|
items * | SegmentedControlItem[] | — | |
value | string | null | null | |
disabled | boolean | false | |
orientation | "horizontal" | "vertical" | "horizontal" | Layout direction. |
iconOnly | boolean | false | Icon-only segments (each item needs an accessible label). |
stacked | boolean | false | Stack icon over label (iOS-style). |
label * | string | — | Accessible name for the control. |
hideLabel | boolean | false | Visually hide the group label (kept for assistive tech). |
name | string | undefined | undefined | Form field name — the selected value is submitted under it. |
onValueChange | ((value: string) => void) | undefined | undefined | Called whenever the selected value changes. |
| Prop | Type | Default | Description |
|---|---|---|---|
items * | SegmentedControlItem[] | — | |
modelValue | string | null | undefined | v-model value; takes precedence over value when bound. |
value | string | null | null | |
disabled | boolean | false | |
orientation | SegmentedControlOrientation | "horizontal" | Layout and arrow-key axis. horizontal (default) is a segment bar; vertical stacks the segments into a column (e.g. a sidebar). Each segment's content stays a row (icon beside label) unless stacked is set. |
iconOnly | boolean | false | Render only the icon for each segment, hiding the visible label (the label still names the segment via aria-label). Items without an icon keep their text. |
stacked | boolean | false | Stack each segment's content vertically: icon on top, label below (e.g. an iOS-style tab). Implies the label stays visible. |
label * | string | — | Accessible name for the control (announced by screen readers). |
hideLabel | boolean | false | Visually hide the label (kept for assistive tech). |
name | string | undefined | Form field name; the selected value is submitted under it. |
onValueChange | (value: string) => void | undefined | Called whenever the selected value changes. |
| Event | Payload |
|---|---|
update:modelValue | value: string | null |
| Prop | Type | Default | Description |
|---|---|---|---|
items * | SegmentedControlItem[] | — | |
value | string | null | null | Initial (uncontrolled) or current (controlled) selected value. |
disabled | boolean | false | |
orientation | SegmentedControlOrientation | "horizontal" | Layout and arrow-key axis. horizontal (default) is a segment bar; vertical stacks the segments into a column (e.g. a sidebar). Each segment's content stays a row (icon beside label) unless stacked is set. |
iconOnly | boolean | false | Render only the icon for each segment, hiding the visible label (the label still names the segment via aria-label). Items without an icon keep their text. |
stacked | boolean | false | Stack each segment's content vertically: icon on top, label below (e.g. an iOS-style tab). Implies the label stays visible. |
label * | string | — | Accessible name for the control (announced by screen readers). |
hideLabel | boolean | false | Visually hide the label (kept for assistive tech). |
name | string | — | Form field name; the selected value is submitted under it. |
onValueChange | (value: string) => void | — | Called whenever the selected value changes. |
| Attribute | Reactive | Description |
|---|---|---|
label * | yes | |
value | yes | |
name | yes | |
orientation | yes | horizontal|vertical |
disabled | yes | |
icon-only | yes | |
stacked | yes | |
hide-label | yes |
Reactive attributes re-render the element when they change after the first render.
Properties: value, items.
Emits: bubbling change CustomEvent with detail.value.
Accessibility
Section titled “Accessibility”- Built on native
<input type="radio">segments: the browser handles roving tabindex, arrow navigation and form participation. - The control needs an accessible name via
label.
Example
Section titled “Example”<SegmentedControl label="View" value="list" items={[ { value: "list", label: "List" }, { value: "grid", label: "Grid" }, ]} onValueChange={(v) => (view = v)}/>In React, an item’s icon is any element:
<SegmentedControl label="View" value={view} items={[ { value: "list", label: "List", icon: <ListIcon /> }, { value: "grid", label: "Grid", icon: <GridIcon /> }, ]} iconOnly onValueChange={setView}/>Themeable via --ds-segment-*.