Segmented Control | Calcite Design System

Segmented Control is a single-choice selector in the form of rectangular visuals.

Overview

Functionality is similar to Radio Buttons, but is visually more prominent.

Sample

Usage

Need for more visual prominence than Radio Button
Workflow view switching
Single-choice interactions in forms

Component comparison

Segmented Control, Radio Buttons, and Checkboxes all support selection, but serve different needs.

Segmented Control

This component

Best for choosing one option from a group of two or more related options. Preferred for visual emphasis, custom styling, or icon support.

Allows only one option to be selected. Selection cannot be cleared.

Radio Button

Alternative

Best for choosing one option from a group of two or more related options.

Allows only one option per Radio Button Group to be selected. Selection cannot be cleared.

Checkbox

Alternative

Best for boolean choices when used individually, or for selecting multiple options using separate checkboxes.

Allows each option to be selected or unselected.

Best practices

Segmented Control `appearance`	Usage
`"solid"`	For primary selections. Solid Segmented Control Items draw more attention than outline.
`"outline"`	To be used for secondary selections. Consist of text and a border with a foreground fill.

Correct Segmented Control content length

Do use Segmented Controls to switch among workflow choices.

Avoid using Segmented Controls as page navigation.

Accessibility

Key	Function
`Arrow left`	Moves focus and selection to previous `calcite-segmented-control-item`. If the current focus and selection is the first `calcite-segmented-control-item`, the focus and selection will cycle to the last `calcite-segmented-control-item`.
`Arrow right`	Moves focus and selection to next `calcite-segmented-control-item`. If the current focus and selection is the last `calcite-segmented-control-item`, the focus and selection will cycle to the first `calcite-segmented-control-item`.
`Arrow down`	Moves focus and selection to previous `calcite-segmented-control-item`. If the current focus and selection is the first `calcite-segmented-control-item`, the focus and selection will cycle to the last `calcite-segmented-control-item`.
`Arrow up`	Moves focus and selection to next `calcite-segmented-control-item`. If the current focus and selection is the last `calcite-segmented-control-item`, the focus and selection will cycle to the first `calcite-segmented-control-item`.
`Tab`	Moves focus in and out of component.
`Tab` and `Shift`	Moves focus in and out of component.

Writing and copy

Keep text for Segmented Controls simple and succinct
Avoid using more than 1-2 words in each item
Do not use punctuation like commas or periods in Segmented Control text
Do not use contractions, such as "you're", "aren't", "can't", and "haven't" to reduce confusion
Avoid writing Segmented Control text as questions
Recommended character maximum for each calcite-segmented-control-item: 20

API reference

Properties

Property	Attribute	Description	Type	Default
appearance	appearance	Specifies the appearance style of the component.	`Extract<"outline" \| "outline-fill" \| "solid", Appearance>`	`"solid"`
disabled	disabled	When `true`, interaction is prevented and the component is displayed with lower opacity.	`boolean`	`false`
form	form	Specifies the `id` of the component's associated form. When not set, the component is associated with its ancestor form element, if one exists.	`string`
labelText	label-text	Specifies the component's label text.	`string`
layout	layout	Defines the layout of the component.	`Extract<"horizontal" \| "vertical", Layout>`	`"horizontal"`
messageOverrides		Overrides individual strings used by the component.	`Record<string, unknown> \| undefined`
name	name	Specifies the name of the component. Required to pass the component's `value` on form submission.	`string`
required	required	When `true` and the component resides in a form, the component must have a value in order for the form to submit.	`boolean`	`false`
scale	scale	Specifies the size of the component.	`Scale`	`"m"`
selectedItemread-only		The component's selected item `HTMLElement`.	`SegmentedControlItem`
status	status	Specifies the status of the validation message.	`Status`	`"idle"`
validationIcon	validation-icon	Specifies the validation icon to display under the component.	`IconName \| boolean`
validationMessage	validation-message	Specifies the validation message to display under the component.	`string`
validityread-only		The component's current validation state.	`MutableValidityState`
value	value	The component's `selectedItem` value.	`string`
width	width	Specifies the width of the component. [Deprecated] The `"half"` value is deprecated, use `"full"` instead.	`Extract<"auto" \| "full", Width>`	`"auto"`

Slots

Name	Description
default (unnamed)	A slot for adding `calcite-segmented-control-item`s.
label-content	A slot for rendering content next to the component's `labelText`.

Styles

Name	Description
--calcite-segmented-control-border-color	Specifies the component's border color.

Events

Name	Description	Behavior
calciteSegmentedControlChange	Fires when the `calcite-segmented-control-item` selection changes.	bubblescomposed

Methods

Name	Description	Signature
componentOnReady	Create a promise that resolves once component is fully loaded.	`componentOnReady(): Promise<this>`
setFocus	Sets focus on the component.	`setFocus(options?: FocusOptions): Promise<void>`