Switch

Switch is a binary control used as a toggle between two different states. When engaged, the thumb travels within the track to indicate change of state. Use it for adjusting settings, preferences or actions within an application or system.

Also known as: Light switch, Toggle, Toggle switch
Salt package@salt-ds/core
Available since1.10.0
Code
Note: This tab list includes overflow; tab positions may be inaccurate or change when a tab is selected

Switch

By default, the switch thumb sits to the left side of the track and is in an unchecked state.

  • You can set the switch state using the optional defaultChecked prop.
  • You can use the onChange event to read the value using the second parameter.

Best practices

  • Only use the checked prop for a controlled switch that requires some logic for validating value.
  • We recommend that you always use a text description for a switch.

Checked

When defaultChecked={true}, switch is in a checked state, and the switch thumb sits to the right side of the track.

Disabled

You can set a switch to a disabled state. When disabled, it's not interactive or focusable.

Best practices

Use a disabled state for switches that have permissions, dependencies or prerequisites. For example, you can disable a switch in a form because the user hasn't yet completed an earlier section of the form.

Disabled checked

You can set a checked switch to a disabled state. When disabled, it's not interactive or focusable. This shows an option has been “checked” but the user cannot change it.

Best practices

Use a disabled checked state for switches that have permissions, dependencies or pre-requisites. For example, a switch in a form may be in a checked state but disabled as the user doesn't have permissions to edit their selection during a later stage in a form.

Read-only

A read-only switch allows the user to focus the control, but doesn't allow them to change its state. You can set a switch as read-only via the prop readOnly.

Note: We recommend avoiding read-only switches due to the lack of adequate aria-readonly support and conflicting user expectations. If you must use a read-only switch, you should always add an accessible name that makes it obvious the switch is read-only, be that via a visual label or an aria-label if there's no space for a visual label.

Best practices

Read-only switches are navigable using keyboard shortcuts. This means that, unlike disabled switches, users can interact with the text description. Use a read-only switch instead of a disabled switch when the text description contains information that is valuable to the user.

Left aligned label

Use a form field if you need a left aligned label, avoid also having a switch label.