Segmented ControlForm-associated

2.59 KB gzip2.23 KB brotli2.68 KB zstd

sv-segmented-control is a single-selection control, comparable to a radio button group, that submits its selected value with forms.

Usage

<label for="plan">Choose a plan</label>

<sv-segmented-control id="plan" value="1">
  <button value="1">Personal</button>
  <button value="2">Business</button>
  <button value="3">Enterprise</button>
  <button value="4" disabled>Custom</button>
</sv-segmented-control>

Only direct child <button> elements become options, and each one needs its own value. When two share a value, the first of them is the one that gets selected.

Selection states

The selected background is painted by two different things: a pill that slides between buttons while the animation runs, and the button itself once it settles. Style both and keep the fills identical, otherwise the color jumps at the end of the animation:

/* Moving pill, visible only during the animation */
sv-segmented-control::part(indicator) {
  background-color: hotpink;
}

/* Resting background, applied when the animation finishes */
sv-segmented-control button[data-sv-active]::before {
  background-color: hotpink;
}

data-sv-active only lands once the animation finishes. Anything that has to change at once, such as text color or an icon, belongs on aria-checked="true" instead.

Setting value from script applies data-sv-active right away and skips the animation, unless you call animateIndicator(). Reduced motion ends up in the same place, since it sets --sv-toggle-dur to 0s.

Keyboard

Key	Behavior
`ArrowRight`, `ArrowDown`	Selects the next enabled option, wrapping round
`ArrowLeft`, `ArrowUp`	Selects the previous enabled option, wrapping

Arrow keys select as they move, the same as a native radio group.

Accessibility

The control is a radio group wearing a different visual style. Name it with <label for>, aria-label, or aria-labelledby.

API References

Methods

`animateIndicator()`

Animate the indicator programmatically.

type AnimateIndicatorOptions = {
  value: string;
  previousValue: string;
  duration?: number;
  easing?: string;
};

Type (options: AnimateIndicatorOptions) => void

Properties

`data`

Sets up the segmented control using an array of SegmentedControlData.
Any existing buttons are removed before new ones are created.

Type { value: string; label: string; disabled: boolean; }[]Write-only

`value`

The current selected value.

Type string

`required`

If true, the user must select a value before submitting a form.

Type booleanReflects "required" attribute

`disabled`

Disable the whole group preventing to select any option.

Type booleanReflects "disabled" attribute

`name`

The name of the control, submitted with the form data.

Type stringReflects "name" attribute

Attributes

`"orientation"`

Controls the layout direction of the segmented control.

Tip

Use the style flex-direction: column|row on the "container" CSS part to control the orientation through CSS. This will override the orientation attribute.

@media (max-width: 600px) {
  sv-segmented-control::part(container) {
    flex-direction: column;
  }
}

Default: "horizontal"

Values "horizontal", "vertical"

`"disabled"`

Prevents user interaction.

Type boolean

`"value"`

The current selected value.

Type string

`"required"`

If true, the user must select a value before submitting a form.

Type boolean

Events

`valuechange`

Fired after the user clicks a segmented control button and changes the value.

Only triggers for user interaction, not programmatic changes.

Type CustomEvent<{ value: string; previousValue: string; }>

`beforevaluechange`

Fired when the user clicks a segmented control button just before changing the value.

Type CustomEvent<{ value: string; previousValue: string; }>Cancelable

Slots

Name	Description
`Default`	The buttons which represent the segmented control options.

CSS Properties

Name	Description
`--sv-sp-around`	Spacing between the buttons and the container edge.
`--sv-toggle-ease`	Easing curve used for toggle animations.
`--sv-toggle-dur`	Duration of the toggle animation.
`--sv-gray-6`	Background color for the container and all inactive buttons.
`--sv-accent`	Background color applied to the selected (active) button.
`--sv-accent-content`	Text color for the selected (active) button.
`--sv-gray-2`	Text color for buttons that are not selected.
`--sv-gray-5`	Border color applied to the container.
`--sv-bdr-sz-sm`	Thickness of the container’s border.
`--sv-bdr-rad-lg`	Border radius for both the container and its buttons. Button radius is derived from this value and the surrounding spacing.

CSS Parts

Name	Description
`::part(container)`	Segmented control container element.
`::part(indicator)`	Segmented control indicator element.