ToggleSwitch

Components/Form

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

Overview

Copy

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

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

States

Disable the component with the disabled prop.

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

Copy

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

Copy

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

Settings

Use toggle switch to turn settings on and off.

Copy

Forms

Use toggle switch to control the state of items.

Copy

Required fields

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

Copy

Code

Copy

Props

NameTypeDefaultDescription
checkedboolean—Specifies whether toggle is checked.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
disabledboolean—Specifies whether toggle is disabled.
idstring—Assigns an unique identifier for the root element.
onChangeChangeEventHandler—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.
tabIndexnumber—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)
  • 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)
  • 1.172.0 (2025-03-20) — breaking: theme (#14639)
  • 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

Last updated: 22 October 2026

Did this help?