> 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: ToggleSwitch Component

## Article: ToggleSwitch Component

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

## Article Content:

# ToggleSwitch

_Components/Form_

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

## Overview

```jsx
() => {
  const [toggled, setToggled] = React.useState(true);
  return (
    <Box align="center">
      <FormField
        labelPlacement="left"
        label="Show image"
        stretchContent={false}
      >
        <ToggleSwitch checked={toggled} onChange={() => setToggled(!toggled)} />
      </FormField>
    </Box>
  );
};
```

Toggle switch turns settings on/off. It lets users switch between two mutually exclusive states.

### Do

- Use it to turn a state, setting, or function on or off.
- Use it to activate or deactivate something immediately.

### Don't

- Don't use toggle switch when states aren't mutually exclusive. Use `<Checkbox/>` instead.
- Don't require users to click on "Save" or "Submit" for toggle switches to take effect.
- Don't use it in place of buttons.

### Feature examples

#### Size

Adjust the component's size using the `size` prop. Three sizes are supported:

- `large` is the default used in form layouts.
- `medium` is for card headers and dense layouts.
- `small` should only be used in very concentrated layouts.

```jsx
<StorybookComponents.Stack>
  <ToggleSwitch size="large" checked />
  <ToggleSwitch size="medium" checked />
  <ToggleSwitch size="small" checked />
</StorybookComponents.Stack>;
```

#### Skin

Style the component using the `skin` prop. Four skins are supported:

- `standard` is the default used for all common cases.
- `success` can be used to highlight that a toggle is "available" or "successfully working."
- `error` highlights that a value is destructive or invalid.
- `urgent` highlights the switch for extra attention.

```jsx
<StorybookComponents.Stack>
  <ToggleSwitch skin="standard" checked />
  <ToggleSwitch skin="success" checked />
  <ToggleSwitch skin="error" checked />
  <ToggleSwitch skin="urgent" checked />
</StorybookComponents.Stack>;
```

#### States

Disable the component with the `disabled` prop.

Use the `checked` prop to show a toggle switch is "on."

```jsx
<StorybookComponents.Stack flexDirection="column">
  <StorybookComponents.Stack>
    <FormField label="Default" stretchContent={false} labelPlacement="right">
      <ToggleSwitch />
    </FormField>
  </StorybookComponents.Stack>
  <StorybookComponents.Stack>
    <FormField label="Checked" stretchContent={false} labelPlacement="right">
      <ToggleSwitch checked />
    </FormField>
  </StorybookComponents.Stack>
  <StorybookComponents.Stack>
    <FormField
      label="Checked Disabled"
      stretchContent={false}
      labelPlacement="right"
    >
      <ToggleSwitch checked disabled />
    </FormField>
  </StorybookComponents.Stack>
  <StorybookComponents.Stack>
    <FormField label="Disabled" stretchContent={false} labelPlacement="right">
      <ToggleSwitch disabled />
    </FormField>
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

#### Status message

Add text that explains the status or what action the user should take with the `statusMessage` prop.

Show the status message inline, directly below the toggle switch by wrapping it in a `<FormField/>` and adding `statusMessage`.

View more inline status message examples in `<FormField/>`.

```jsx
<FormField status="error" statusMessage="This is an error message.">
  <ToggleSwitch />
</FormField>;
```

### Common use case examples

#### With a label

Wrap toggle switch in `<FormField/>` to:

- Give it a `label`.
- Mark it as `required`.
- Give additional information in the hover tooltip.

```jsx
() => {
  const [toggleChecked, setToggleChecked] = React.useState(true);

  return (
    <Box>
      <FormField
        labelPlacement="right"
        label="Label"
        required
        infoContent="This tooltip provides some additional info about the control."
        stretchContent={false}
      >
        <ToggleSwitch
          checked={toggleChecked}
          onChange={() => setToggleChecked(!toggleChecked)}
        />
      </FormField>
    </Box>
  );
};
```

#### Settings

Use toggle switch to turn settings on and off.

```jsx
() => {
  const renderListItem = ({ title, subtitle, padding, toggleChecked }) => {
    const [checked, setChecked] = React.useState(toggleChecked);

    return (
      <Box verticalAlign="middle" align="space-between" padding={padding}>
        <Box direction="vertical">
          <Text weight="normal">{title}</Text>
          <Text secondary size="small">
            {subtitle}
          </Text>
        </Box>
        <ToggleSwitch checked={checked} onChange={() => setChecked(!checked)} />
      </Box>
    );
  };

  return (
    <Card>
      <Card.Header
        title="Default emails"
        subtitle="Send default notifications about this event."
      />
      <Card.Divider />
      <Card.Content>
        <Box direction="vertical">
          {renderListItem({
            title: 'Confirmation',
            subtitle: 'Let guests know their spot is confirmed.',
            padding: '0px 0px 18px',
            toggleChecked: false,
          })}
          <Divider />

          {renderListItem({
            title: 'Reminder',
            subtitle: 'Send a friendly reminder when the event is coming up.',
            padding: '18px 0px',
            toggleChecked: true,
          })}
          <Divider />

          {renderListItem({
            title: 'Cancelation',
            subtitle: 'Notify guests if this event is canceled.',
            padding: '18px 0px 0px',
            toggleChecked: true,
          })}
        </Box>
      </Card.Content>
    </Card>
  );
};
```

#### Forms

Use toggle switch to control the state of items.

```jsx
() => {
  const [toggleChecked, setToggleChecked] = React.useState(true);

  return (
    <Card>
      <Card.Header title="Product info" />
      <Card.Divider />
      <Card.Content>
        <Layout cols={12}>
          <Cell span={12}>
            <Heading size="tiny">Basic info</Heading>
          </Cell>
          <Cell span={8}>
            <FormField label="Product name">
              <Input placeholder=" " />
            </FormField>
          </Cell>
          <Cell span={4}>
            <FormField label="Ribbon">
              <Input placeholder="e.g., New Arrival" />
            </FormField>
          </Cell>
          <Cell span={4}>
            <FormField label="Price">
              <NumberInput
                prefix={<Input.Affix>$</Input.Affix>}
                hideStepper
                value="12"
              />
            </FormField>
          </Cell>
          <Cell span={12}>
            <Box>
              <FormField
                stretchContent={false}
                label="On sale"
                labelPlacement="right"
              >
                <ToggleSwitch
                  checked={toggleChecked}
                  onChange={() => setToggleChecked(!toggleChecked)}
                />
              </FormField>
            </Box>
          </Cell>
          <Cell span={4}>
            <FormField label="Discount">
              <NumberInput
                suffix={<Input.Affix>%</Input.Affix>}
                hideStepper
                value="20"
              />
            </FormField>
          </Cell>
          <Cell span={4}>
            <FormField label="Sale price">
              <NumberInput
                prefix={<Input.Affix>$</Input.Affix>}
                hideStepper
                value="12"
              />
            </FormField>
          </Cell>
          <Cell span={12}>
            <FormField label="Description">
              <RichTextInputArea minHeight="120px" />
            </FormField>
          </Cell>
        </Layout>
      </Card.Content>
    </Card>
  );
};
```

#### Required fields

Use toggle switch to set a field as required or optional.

```jsx
() => {
  const [selectedOption, setSelectedOption] = React.useState(0);
  const [value, setValue] = React.useState(2);
  const [toggleChecked, setToggleChecked] = React.useState(true);

  const options = [
    { id: 0, value: 'Image' },
    { id: 1, value: 'Video' },
    { id: 2, value: 'Image and video' },
    { id: 3, value: 'Document' },
    { id: 4, value: 'Audio' },
  ];
  return (
    <SidePanel maxHeight="576px" width="288px" skin="floating">
      <SidePanel.Header title="Upload Settings" />
      <SidePanel.Content noPadding>
        <SidePanel.Field>
          <FormField label="Supported file type">
            <Dropdown
              placeholder="Select"
              size="small"
              options={options}
              onSelect={(option) => setSelectedOption(Number(option.id))}
              selectedId={selectedOption}
            />
          </FormField>
        </SidePanel.Field>
        <SidePanel.Field>
          <FieldSet
            gap="small"
            legend="Max number of files"
            columns="auto 72px"
          >
            <Slider
              onChange={(v) => setValue(Number(v))}
              min={0}
              max={10}
              value={value}
              displayMarks={false}
            />
            <Input
              size="small"
              value={value}
              onChange={(e) => setValue(Number(e.target.value))}
            />
          </FieldSet>
        </SidePanel.Field>
        <SidePanel.Field>
          <FormField label="Is required" labelPlacement="left" labelWidth="1fr">
            <ToggleSwitch
              size="medium"
              checked={toggleChecked}
              onChange={() => setToggleChecked(!toggleChecked)}
            />
          </FormField>
        </SidePanel.Field>
        <SidePanel.Section title="Display settings">
          <SidePanel.Field>
            <FormField label="Field title">
              <Input size="small" placeholder="Enter field title" />
            </FormField>
          </SidePanel.Field>
          <SidePanel.Field>
            <FormField label="Button text">
              <Input size="small" value="Choose file" />
            </FormField>
          </SidePanel.Field>
        </SidePanel.Section>
      </SidePanel.Content>
    </SidePanel>
  );
};
```

## Code

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

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | — | Specifies whether toggle is checked. |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in the tests. |
| `disabled` | `boolean` | — | Specifies whether toggle is disabled. |
| `id` | `string` | — | Assigns an unique identifier for the root element. |
| `onChange` | `ChangeEventHandler` | — | Defines a callback that receives the input change event when the toggle state changes. |
| `size` | `"small" \| "medium" \| "large"` | `'large'` | Controls the size of a toggle. |
| `skin` | `"error" \| "standard" \| "success" \| "urgent"` | `'standard'` | Controls the skin of a toggle. |
| `tabIndex` | `number` | — | Indicates that element can be focused and where it participates in sequential keyboard navigation. |

## 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) — fix: pressing Enter provides an input change event with the updated checked value, matching mouse and Space activation. ([#17480](invalid-url))
- **1.338.0** (2026-10-15) — maintenance release, no component-specific changes
- **1.330.1** (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.323.0** (2026-09-10) — maintenance release, no component-specific changes
- **1.318.0** (2026-08-28) — maintenance release, no component-specific changes
- **1.310.0** (2026-08-10) — maintenance release, no component-specific changes
- **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.278.0** (2026-05-08) — maintenance release, no component-specific changes
- **1.273.0** (2026-04-30) — maintenance release, no component-specific changes
- **1.272.0** (2026-04-27) — maintenance release, no component-specific changes
- **1.271.0** (2026-04-22) — maintenance release, no component-specific changes
- **1.266.0** (2026-04-07) — maintenance release, no component-specific 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.244.0** (2026-01-02) — fix: a11y triggering with keyboard ([#15733](invalid-url))
- **1.172.0** (2025-03-20) — breaking: theme ([#14639](invalid-url))
- **1.138.1** (2024-10-30) — maintenance release, no component-specific changes
- **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.103.1** (2024-04-24) — maintenance release, no component-specific changes
- **1.102.0** (2024-04-16) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes