Segmented control

A single selected value using native radios styled as buttons.

When to use

Use a segmented control for one selected value from a short, visible set, such as a billing interval. It uses native Radios, including form submission, reset and keyboard navigation. Use native Buttons with existing Flex and Spacing utilities for related independent actions, or Tabs for switching panels.

Class reference

Class Purpose
.segmented-control Wrapping container for choices.
.segmented-control-option Label wrapping one radio and its visible button surface.
.segmented-control-input Visually hidden, focusable native radio.
.segmented-control-equal Fill the available width with equal-width choices.
.btn.btn-primary.btn-outline Existing button surface on the span immediately after the radio.

Single selection

Use a fieldset and legend to name the group. Each wrapping label names its radio. Give radios the same name and distinct value attributes; use a different name for every independent group. Set the initial selection with checked.

Billing interval
HTML
<fieldset class="border border-0 min-w-0">
	<legend class="mb-2">Billing interval</legend>
	<div class="segmented-control">
		<label class="segmented-control-option">
			<input
				class="segmented-control-input"
				type="radio"
				name="billing"
				value="monthly"
				checked />
			<span class="btn btn-primary btn-outline">Monthly</span>
		</label>
		<label class="segmented-control-option">
			<input class="segmented-control-input" type="radio" name="billing" value="yearly" />
			<span class="btn btn-primary btn-outline">Yearly</span>
		</label>
	</div>
</fieldset>

Compact, equal widths and icons

Add .segmented-control-equal to fill the container. Put .btn-sm or .btn-lg on every visible span to change size. Keep text alongside decorative icons, or provide a visually hidden label for an icon-only choice.

Appearance

Vertical and responsive layout

Add .flex-column to .segmented-control for vertical choices and .flex-md-row to return to a row at the medium breakpoint. Choices wrap by default; long labels can break inside their surface. Layout follows dir="rtl". Orientation classes change layout; native radio keyboard behavior remains browser controlled.

Locked delivery method

Accessibility and behavior

  • Tab enters the native radio group; arrow keys move and select, and Space selects the focused choice. Native checked state is the source of truth; do not add aria-pressed, tab roles or visual .is-active state.
  • Keep the radio immediately before its visible .btn span inside the label. The radio remains focusable and its keyboard-focus outline appears on the visible surface.
  • Only the checked, enabled radio contributes its name and value to a form. Native reset restores the initial selection. Use required when a selection is mandatory and no initial value is provided.
  • Disable an individual radio with disabled or the entire fieldset with disabled. Selected choices also have an underline, which remains visible in forced-colors mode and when disabled.
  • No JavaScript or initialization is needed, including after Astro navigation. Listen to native change events in application code if the selected value should update other content.

CSS variables

Override these base defaults on the listed selector after the library styles. Variants and states may replace them; global tokens follow the active theme.

TokenDefaultPurposeScope / state
--segmented-control-gapvar(--spacer-1)Space between choices..segmented-control

The visible spans use the existing Button CSS variables. For selective Sass imports, load the shared tokens followed by @use '@oardi/css-utils/components/segmented-control'; the component includes the button styles.