SegmentedToggle

Components/Form

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/segmentedtoggle

Overview

Copy

Segmented toggles are sets of buttons that allow users to choose from multiple options. Only a single option can be selected at a time.

Do

  • Allow users to switch between alternative views of data, or to change the status of an item.
  • Allow users to toggle between options.

Don't

  • Don't organize content within a page with them. Use <Tabs/> instead.
  • Don't let users select multiple options at once. Use <ToggleButton/> instead.

Feature examples

Structure

Use the SegmentedToggle to wrap a set of related options. It should be used to present two to five options.

Copy

Child items

Each button should be set as a child item of the component.

  • Use <SegmentedToggle.Button/> for text labels.
  • Use <SegmentedToggle.Icon/> when short on space, or when there's enough context to make the option distinguishable only using icons.
Copy

Size

Adjust the size of the component with the size property.

  • Use medium as the default in all forms, card or page layouts.
  • Use small in compact environments.
  • Use tiny in very dense layouts.
Copy

Prefix icon

Add an icon next to the option label using <SegmentedToggle.Button/> to make it easier to scan.

Copy

Disabled options

Disable buttons with the disabled prop. Use it to disable the whole composite.

Copy

Developer examples

Selection control

The component value can be controlled manually using the selected prop.

Copy

Common use case examples

Settings panel

Use a segmented toggle to let users control element settings.

Copy

Switch between views

Use segmented toggles to let users switch between different layouts, such as between a grid or a list view.

Copy

Status toggle

Use segmented toggles to let users control an item's status.

Copy

Code

Copy

Props

NameTypeDefaultDescription
ariaLabelstring—Accessible label for the segmented toggle group.
ariaLabelledbystring—ID of element that labels the segmented toggle group.
children (required)any[]—Accepts <SegmentedToggle.Icon/> or <SegmentedToggle.Button/> as child items to list down available options.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
defaultSelectedReactNode—Specifies the initially selected option.
disabledboolean—Specifies whether interactions are disabled.
fullWidthboolean—Makes the container take up entire width.
onClick(event: SyntheticEvent<Element, Event>, value: string) => void—Defines a callback function which is called every time option is clicked. Returns a selected element and its value.
onKeyDownKeyboardEventHandler<HTMLDivElement>—Defines a keyboard callback; calling preventDefault() prevents arrow-key navigation.
selectedReactNode—Specifies whether an option is selected.
size"small" | "tiny" | "medium"'medium'Controls the size of the segmented toggle.

Testkit

No testkit for this component — it doesn't expose a unidriver testkit.

Changelog

  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.336.0 (2026-10-13) — fix: Tab enters and leaves the group once, and arrow keys select enabled options while moving focus. (#17426)
  • 1.330.3 (2026-09-29) — maintenance release, no component-specific changes
  • 1.330.0 (2026-09-28) — maintenance release, no component-specific changes
  • 1.329.0 (2026-09-24) — maintenance release, no component-specific changes
  • 1.328.0 (2026-09-22) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.324.0 (2026-09-14) — maintenance release, no component-specific changes
  • 1.323.0 (2026-09-10) — maintenance release, no component-specific changes
  • 1.315.0 (2026-08-20) — fix: fixed a build failure ("Unknown node type in node creation") in apps that process the odeditor global stylesheets with autoprefixer, introduced in 1.313.0 by the sliding selection indicator's @supports rule. (#16853)
  • 1.313.1 (2026-08-18) — feat: the selected-segment highlight now slides between segments in the Harmony theme instead of jumping. Implemented in CSS only (anchor positioning), shipped solely in the Harmony theme stylesheet; browsers without anchor-positioning support (currently Firefox) keep the previous instant selection change. (#16630)
  • 1.312.0 (2026-08-14) — fix: selected button no longer loses its selected colors after tapping on touch devices. (#16815)
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.305.1 (2026-07-30) — maintenance release, no component-specific changes
  • 1.305.0 (2026-07-28) — feat: migrate to semantic classnames (#16575)
  • 1.295.0 (2026-07-03) — maintenance release, no component-specific changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.291.0 (2026-06-19) — maintenance release, no component-specific changes
  • 1.282.0 (2026-05-27) — fix: fixed issue with height on segmented toggle (#16302) — has visual changes
  • 1.280.0 (2026-05-19) — fix: reduce icon-only horizontal padding in odeditor themes (#16280)
  • 1.277.0 (2026-05-07) — feat: add inner-shadow-fill tokens for odeditor-dark (#16235)
  • 1.273.0 (2026-04-30) — maintenance release, no component-specific changes
  • 1.272.0 (2026-04-27) — feat: added new fullwidth property to segmentedtoggle (#16202) — has visual changes
  • 1.267.0 (2026-04-09) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — feat: added new size tiny (#16106) — has visual changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.247.2 (2026-01-21) — maintenance release, no component-specific changes
  • 1.246.0 (2026-01-09) — maintenance release, no component-specific changes
  • 1.243.0 (2025-12-23) — maintenance release, no component-specific changes
  • 1.241.0 (2025-12-17) — maintenance release, no component-specific changes
  • 1.220.2 (2025-10-06) — maintenance release, no component-specific changes
  • 1.217.0 (2025-09-08) — breaking: e3 container border radius (#15280)
  • 1.214.3 (2025-08-25) — fix: fix disabled prop to SegmentedToggle.Button (#15239)
  • 1.213.0 (2025-08-19) — breaking: update size (#15176)
  • 1.212.0 (2025-08-11) — maintenance release, no component-specific changes
  • 1.211.0 (2025-08-07) — breaking: tokenize (#15150)
  • 1.201.0 (2025-06-23) — maintenance release, no component-specific changes
  • 1.198.1 (2025-06-09) — feat: add radiogroup and radio roles (#14955)
  • 1.197.0 (2025-06-06) — maintenance release, no component-specific changes
  • 1.176.0 (2025-04-02) — breaking: tokenization for Wixel gaps (#14663)
  • 1.155.0 (2025-01-23) — feat: add isDisabled method to testkit (#14460)
  • 1.128.0 (2024-09-19) — maintenance release, no component-specific changes
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.102.0 (2024-04-16) — breaking: buttons share width equally (#13580)
  • 1.99.0 (2024-03-29) — fix: allow overriding internal tooltip props of SegmentedToggle.Icon (#13518)
  • 1.98.0 (2024-03-15) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 22 October 2026

Did this help?