SegmentedControl

Compact single-choice control for switching modes.

Overview

  • Use short, mutually exclusive labels. Use Tabs when each choice controls a separate content panel.

Aliases

segments

When to use

  • Use SegmentedControl for compact mode switches such as day, week, and month, or card and list.
  • Keep labels short so the control stays scan-friendly.

When not to use

  • Do not use SegmentedControl for long or descriptive options; use RadioGroup instead.
  • Use Tabs when each option controls a content panel.

Structural parts

segmented group

root

Holds the compact option cluster.

single segment

item

Each mutually exclusive segment button.

Public interface

Props
NameTypeDefaultDescription
valuestring—Controlled selected segment.
itemsArray<{ value: string; label: string; disabled?: boolean }>—Segment definitions.
size'sm' | 'md''md'Chooses the size recipe.
onChange(detail: { value: string }) => void—Runs when the selected segment changes.
themeThemeContract—Sets the theme used to resolve component styles.
Events
NamePayloadDescription
change{ value: string }Fires with the selected segment value.
Slots
NameDescription
defaultSegmentedControl is data-driven and does not expose segment slots.

Variants, sizes, and states

Variants

  • default: SegmentedControl uses one compact mode-switching recipe.

Sizes

  • sm: Compact segments
  • md: Default segments

States

  • rest: Unselected segment
  • selected: Active segment
  • disabled: Unavailable segment

Accessibility

Semantics

  • Exposes a single-selection grouped control with clearly labeled options.

Keyboard

  • Arrow keys move focus and selection between enabled segments.

Screen readers

  • Identify selection with text or state attributes as well as color.

Checklist

  • Verify that the control has an accessible name.
  • Verify that keyboard focus is visible in every state and size.
  • Identify disabled, selected, and error states with text or symbols as well as color.

Tokens and CSS variables

root

--dk-segmented-gap
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)

group

--dk-segmented-group-bg
#e5e8ed
--dk-segmented-group-border
#95989d
--dk-segmented-group-radius
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
--dk-segmented-group-gap
clamp(0.563rem, 0.5156rem + 0.208vw, 0.703rem)
--dk-segmented-group-padding
0.1875rem

item

--dk-segmented-item-bg
#e5e8ed
--dk-segmented-item-fg
#16181c
--dk-segmented-item-radius
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
--dk-segmented-item-block-size
44px
--dk-segmented-item-inline-padding
clamp(1.778rem, 1.6296rem + 0.658vw, 2.222rem)
--dk-segmented-item-font-size
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-segmented-item-font-weight
650

label

--dk-segmented-label-size
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)

Examples

Starter

Mode switch

A compact day, week, and month switch.

<SegmentedControl items={[{ value: 'day', label: 'Day' }, { value: 'week', label: 'Week' }, { value: 'month', label: 'Month' }]} value="week" />

Common patterns

Dense toolbar mode

Smaller segments work well in inspector-style toolbars.

<SegmentedControl size="sm" items={viewItems} value="list" />

Edge cases

Unavailable segment

Disable segments when a mode exists conceptually but is not usable yet.

<SegmentedControl items={[{ value: 'day', label: 'Day' }, { value: 'quarter', label: 'Quarter', disabled: true }]} value="day" />

Mathematical fixtures

Calculated fixtures; browser evidence is not collected. Layout estimates use declared text behavior and maximum token values.

default (size=sm)

pass

size=sm

  • Evidence: mathematical
  • Coverage: complete (2 / 2 declared kinds evaluated)
  • Declared: contrast, target
  • Evaluated: contrast, target
  • Contrast: 90.8 Lc
  • Target: 44 px

default (size=md)

pass

size=md

  • Evidence: mathematical
  • Coverage: complete (2 / 2 declared kinds evaluated)
  • Declared: contrast, target
  • Evaluated: contrast, target
  • Contrast: 90.8 Lc
  • Target: 44 px

selected (size=sm)

pass

size=sm

  • Evidence: mathematical
  • Coverage: complete (2 / 2 declared kinds evaluated)
  • Declared: contrast, target
  • Evaluated: contrast, target
  • Contrast: 89.9 Lc
  • Target: 44 px

selected (size=md)

pass

size=md

  • Evidence: mathematical
  • Coverage: complete (2 / 2 declared kinds evaluated)
  • Declared: contrast, target
  • Evaluated: contrast, target
  • Contrast: 89.9 Lc
  • Target: 44 px