Segmented Control | Calcite Design System

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

Overview

Functionality is similar to Radio Button Group, but is visually more prominent.

Sample

Usage

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

Component comparison

Segmented Control, Radio Button Group, 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 Group

Alternative

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

Allows only one option 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

`appearance` property	Example	Usage
`"solid"`		Use for primary or emphasized selections.
`"outline-fill"`		Use for secondary or less-emphasized selections. Consists of text/icons and a border with a background fill.
`"outline"`		Use for secondary or less-emphasized selections. Has no background fill.

Segmented Control with Map selected. Other options include Histogram, Table, and HTML.

Do use Segmented Controls to switch among workflow choices.

Segmented Control used as page navigation, which should be avoided.

Avoid using Segmented Controls as page navigation. Consider using Navigation instead.

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 up`	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 down`	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.	`ValidityState`
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	Creates a promise that resolves once the component is fully loaded.	`componentOnReady(): Promise<this>`
setFocus	Sets focus on the component.	`setFocus(options?: FocusOptions): Promise<void>`