> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: SegmentedToggle Component

## Article: SegmentedToggle Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/form/segmented-toggle-component.md

## Article Content:

# SegmentedToggle

_Components/Form_

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

## Overview

```jsx
<Box align="center">
  <FormField label="Filter by">
    <SegmentedToggle defaultSelected="option1">
      <SegmentedToggle.Button prefixIcon={<Icons.List />} value="option1">
        Size
      </SegmentedToggle.Button>
      <SegmentedToggle.Button prefixIcon={<Icons.ColorDrop />} value="option2">
        Color
      </SegmentedToggle.Button>
    </SegmentedToggle>
  </FormField>
</Box>;
```

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.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <SegmentedToggle defaultSelected="option1">
    <SegmentedToggle.Button value="option1">Option 1</SegmentedToggle.Button>
    <SegmentedToggle.Button value="option2">Option 2</SegmentedToggle.Button>
  </SegmentedToggle>
  <SegmentedToggle defaultSelected="option1">
    <SegmentedToggle.Button value="option1">Option 1</SegmentedToggle.Button>
    <SegmentedToggle.Button value="option2">Option 2</SegmentedToggle.Button>
    <SegmentedToggle.Button value="option3">Option 3</SegmentedToggle.Button>
  </SegmentedToggle>
  <SegmentedToggle defaultSelected="option1">
    <SegmentedToggle.Button value="option1">Option 1</SegmentedToggle.Button>
    <SegmentedToggle.Button value="option2">Option 2</SegmentedToggle.Button>
    <SegmentedToggle.Button value="option3">Option 3</SegmentedToggle.Button>
    <SegmentedToggle.Button value="option4">Option 4</SegmentedToggle.Button>
  </SegmentedToggle>
</StorybookComponents.Stack>;
```

#### 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.

```jsx
<StorybookComponents.Stack>
  <SegmentedToggle defaultSelected="option1">
    <SegmentedToggle.Button value="option1">Option 1</SegmentedToggle.Button>
    <SegmentedToggle.Button value="option2">Option 2</SegmentedToggle.Button>
  </SegmentedToggle>
  <SegmentedToggle defaultSelected="option1">
    <SegmentedToggle.Icon value="option1" tooltipText="Option 1">
      <Icons.LockLocked />
    </SegmentedToggle.Icon>
    <SegmentedToggle.Icon value="option2" tooltipText="Option 2">
      <Icons.LockUnlocked />
    </SegmentedToggle.Icon>
  </SegmentedToggle>
</StorybookComponents.Stack>;
```

#### 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.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <SegmentedToggle defaultSelected="option1" size="medium">
    <SegmentedToggle.Button value="option1">Medium</SegmentedToggle.Button>
    <SegmentedToggle.Button value="option2">Medium</SegmentedToggle.Button>
  </SegmentedToggle>
  <SegmentedToggle defaultSelected="option1" size="small">
    <SegmentedToggle.Button value="option1">Small</SegmentedToggle.Button>
    <SegmentedToggle.Button value="option2">Small</SegmentedToggle.Button>
  </SegmentedToggle>
  <SegmentedToggle defaultSelected="option1" size="tiny">
    <SegmentedToggle.Button value="option1">Tiny</SegmentedToggle.Button>
    <SegmentedToggle.Button value="option2">Tiny</SegmentedToggle.Button>
  </SegmentedToggle>
</StorybookComponents.Stack>;
```

#### Prefix icon

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

```jsx
<SegmentedToggle defaultSelected="option1">
  <SegmentedToggle.Button prefixIcon={<Icons.LockLocked />} value="option1">
    Option 1
  </SegmentedToggle.Button>
  <SegmentedToggle.Button prefixIcon={<Icons.LockUnlocked />} value="option2">
    Option 2
  </SegmentedToggle.Button>
</SegmentedToggle>;
```

#### Disabled options

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

```jsx
<SegmentedToggle defaultSelected="option1" disabled>
  <SegmentedToggle.Button value="option1">Option</SegmentedToggle.Button>
  <SegmentedToggle.Button value="option2">Option</SegmentedToggle.Button>
</SegmentedToggle>;
```

### Developer examples

#### Selection control

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

```jsx
() => {
  const [selectedValue, setSelectedValue] = React.useState('option1');
  const onClick = (_, value) => setSelectedValue(value);

  return (
    <FormField label="Alignment">
      <Box>
        <SegmentedToggle selected={selectedValue} onClick={onClick}>
          <SegmentedToggle.Icon value="option1" tooltipText="Left align">
            <Icons.TextAlignLeft />
          </SegmentedToggle.Icon>
          <SegmentedToggle.Icon value="option2" tooltipText="Center align">
            <Icons.TextAlignCenter />
          </SegmentedToggle.Icon>
          <SegmentedToggle.Icon value="option3" tooltipText="Right align">
            <Icons.TextAlignRight />
          </SegmentedToggle.Icon>
          <SegmentedToggle.Icon value="option4" tooltipText="Justify">
            <Icons.TextJustify />
          </SegmentedToggle.Icon>
        </SegmentedToggle>
      </Box>
    </FormField>
  );
};
```

### Common use case examples

#### Settings panel

Use a segmented toggle to let users control element settings.

```jsx
() => {
  const [value, setValue] = React.useState('');
  return (
    <SidePanel maxHeight="576px" width="288px" skin="floating">
      <SidePanel.Header title="Text Box Settings" />
      <SidePanel.Content noPadding>
        <SidePanel.Field>
          <FormField label="Description">
            <InputArea
              placeholder="Collapsible text is great for longer section titles and descriptions."
              size="small"
              rows={3}
              maxLength={300}
              hasCounter
              resizable
              value={value}
              onChange={(e) => setValue(e.target.value)}
            />
          </FormField>
        </SidePanel.Field>
        <SidePanel.Field>
          <FormField label="What does the button do?">
            <SegmentedToggle size="small" defaultSelected="Open">
              <SegmentedToggle.Button value="Open">
                Expand
              </SegmentedToggle.Button>
              <SegmentedToggle.Button value="Closed">
                Link
              </SegmentedToggle.Button>
            </SegmentedToggle>
          </FormField>
        </SidePanel.Field>
        <SidePanel.Field>
          <FormField label="Link button text">
            <Input size="small" placeholder="Link to full article" />
          </FormField>
        </SidePanel.Field>
      </SidePanel.Content>
    </SidePanel>
  );
};
```

#### Switch between views

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

```jsx
() => {
  const VIEW_TYPE = {
    listView: 'listView',
    tileView: 'tileView',
  };
  const [viewType, setViewType] = React.useState(VIEW_TYPE.listView);

  const changeViewType = (_, value) => setViewType(value);

  const ActionsCell = (
    <TableActionCell
      primaryAction={{
        text: 'Edit',
        skin: 'standard',
        onClick: () => {},
      }}
      secondaryActions={[
        {
          text: 'Move',
          icon: <Icons.MoveToSmall />,
          onClick: () => {},
        },
        {
          text: 'Mark as sold out',
          icon: <Icons.FoodOutOfStockSmall />,
          onClick: () => {},
        },
        {
          text: 'Hide',
          icon: <Icons.HiddenSmall />,
          onClick: () => {},
        },
        {
          text: 'Archive',
          icon: <Icons.ArchiveSmall />,
          onClick: () => {},
        },
      ]}
      numOfVisibleSecondaryActions={0}
    />
  );

  const ListView = () => [
    <TableListItem
      key="1"
      draggable
      showDivider
      options={[
        {
          value: <Image src="FoodExample1.jpg" width="90px" height="52px" />,
          width: '90px',
        },
        { value: <Text>French toast</Text> },
        { value: <Text>$8.00</Text> },
        {
          value: ActionsCell,
        },
      ]}
    />,
    <TableListItem
      key="2"
      draggable
      showDivider
      options={[
        {
          value: <Image src="FoodExample2.jpg" width="90px" height="52px" />,
          width: '90px',
        },
        { value: <Text>House pasta</Text> },
        { value: <Text>$27.00</Text> },
        {
          value: ActionsCell,
        },
      ]}
    />,
    <TableListItem
      key="3"
      draggable
      options={[
        {
          value: <Image src="FoodExample3.jpg" width="90px" height="52px" />,
          width: '90px',
        },
        { value: <Text>Paella</Text> },
        { value: <Text>$18.00</Text> },
        {
          value: ActionsCell,
        },
      ]}
    />,
  ];

  const Tile = ({ media, title }) => (
    <Proportion aspectRatio={1}>
      <MediaOverlay skin="gradient" media={media}>
        <MediaOverlay.Content placement="top-end" visible="hover">
          <IconButton priority="secondary" skin="inverted" size="tiny">
            <Icons.Edit />
          </IconButton>
        </MediaOverlay.Content>
        <MediaOverlay.Content placement="bottom-start" visible="always">
          <Text size="small" weight="normal" light>
            {title}
          </Text>
        </MediaOverlay.Content>
      </MediaOverlay>
    </Proportion>
  );

  const TileView = () => (
    <Card.Content>
      <Layout cols={4}>
        <Tile media="FoodExample1.jpg" title="French toast" />
        <Tile media="FoodExample2.jpg" title="House pasta" />
        <Tile media="FoodExample3.jpg" title="Paella" />
      </Layout>
    </Card.Content>
  );

  return (
    <Card>
      <Card.Header
        title="Dishes"
        suffix={
          <Box gap="18px" verticalAlign="middle">
            <SegmentedToggle selected={viewType} onClick={changeViewType}>
              <SegmentedToggle.Icon
                value={VIEW_TYPE.tileView}
                tooltipText="Tile view"
              >
                <Icons.LayoutGallery />
              </SegmentedToggle.Icon>
              <SegmentedToggle.Icon
                value={VIEW_TYPE.listView}
                tooltipText="List view"
              >
                <Icons.LayoutList />
              </SegmentedToggle.Icon>
            </SegmentedToggle>
            <Button size="small" prefixIcon={<Icons.Add />}>
              Add Dish
            </Button>
          </Box>
        }
      />
      <Card.Divider />
      {viewType === VIEW_TYPE.listView ? <ListView /> : <TileView />}
    </Card>
  );
};
```

#### Status toggle

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

```jsx
() => {
  const [registrationOrigin, setRegistrationOrigin] = React.useState(1);
  return (
    <Card>
      <Card.Header title="Guest registration" />
      <Card.Divider />
      <Card.Content>
        <Layout cols={1}>
          <Box direction="vertical" gap="12px">
            <FormField label="Where do guests register?">
              <RadioGroup
                value={registrationOrigin}
                onChange={(value) => setRegistrationOrigin(Number(value))}
              >
                <RadioGroup.Radio value={1}>
                  On my Wix Events registration page
                </RadioGroup.Radio>
                <RadioGroup.Radio value={2}>
                  On a different page or website
                </RadioGroup.Radio>
                <RadioGroup.Radio value={3}>
                  Guest don't need to register
                </RadioGroup.Radio>
              </RadioGroup>
            </FormField>
          </Box>
          <Divider />
          <FormField label="Registration for this event is:">
            <Box>
              <SegmentedToggle defaultSelected="option1">
                <SegmentedToggle.Button
                  prefixIcon={<Icons.LockUnlocked />}
                  value="option1"
                >
                  Open
                </SegmentedToggle.Button>
                <SegmentedToggle.Button
                  prefixIcon={<Icons.LockLocked />}
                  value="option2"
                >
                  Closed
                </SegmentedToggle.Button>
              </SegmentedToggle>
            </Box>
          </FormField>
        </Layout>
      </Card.Content>
    </Card>
  );
};
```

## Code

```jsx
import { SegmentedToggle } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `ariaLabel` | `string` | — | Accessible label for the segmented toggle group. |
| `ariaLabelledby` | `string` | — | 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. |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in the tests. |
| `defaultSelected` | `ReactNode` | — | Specifies the initially selected option. |
| `disabled` | `boolean` | — | Specifies whether interactions are disabled. |
| `fullWidth` | `boolean` | — | 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. |
| `onKeyDown` | `KeyboardEventHandler<HTMLDivElement>` | — | Defines a keyboard callback; calling `preventDefault()` prevents arrow-key navigation. |
| `selected` | `ReactNode` | — | 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](invalid-url))
- **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](invalid-url))
- **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](invalid-url))
- **1.312.0** (2026-08-14) — fix: selected button no longer loses its selected colors after tapping on touch devices. ([#16815](invalid-url))
- **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](invalid-url))
- **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](invalid-url)) — has visual changes
- **1.280.0** (2026-05-19) — fix: reduce icon-only horizontal padding in odeditor themes ([#16280](invalid-url))
- **1.277.0** (2026-05-07) — feat: add inner-shadow-fill tokens for odeditor-dark ([#16235](invalid-url))
- **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](invalid-url)) — 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](invalid-url)) — 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](invalid-url))
- **1.214.3** (2025-08-25) — fix: fix disabled prop to SegmentedToggle.Button ([#15239](invalid-url))
- **1.213.0** (2025-08-19) — breaking: update size ([#15176](invalid-url))
- **1.212.0** (2025-08-11) — maintenance release, no component-specific changes
- **1.211.0** (2025-08-07) — breaking: tokenize ([#15150](invalid-url))
- **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](invalid-url))
- **1.197.0** (2025-06-06) — maintenance release, no component-specific changes
- **1.176.0** (2025-04-02) — breaking: tokenization for Wixel gaps ([#14663](invalid-url))
- **1.155.0** (2025-01-23) — feat: add isDisabled method to testkit ([#14460](invalid-url))
- **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](invalid-url))
- **1.99.0** (2024-03-29) — fix: allow overriding internal tooltip props of SegmentedToggle.Icon ([#13518](invalid-url))
- **1.98.0** (2024-03-15) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes