A Toggle Switch is used to switch between two states, most commonly “on”/“off”.

AnatomyPermalink to: Anatomy

1. Toggle Switch Container: The container of the control.
2. On indicator: Indicator that shows the Toggle Switch is in the "on" position.
3. Thumb: Togglable element to indicate the change. Can also indicate a locked Toggle Switch.
4. Label: Text that describes very clearly what is being turned on or off.

UsagePermalink to: Usage

Only use the Toggle Switch when the state is automatically saved upon switching.

When to usePermalink to: When to use

• Use inside large data tables, where the user can turn on a setting.

When not to usePermalink to: When not to use

• For forms where the user has to submit by activating a button (ie. “Save” or “Submit”) you should use either a group of Radio Buttons or a Checkbox.

AccessibilityPermalink to: Accessibility

Always make sure that the label for the Toggle Switch is visible.

If the Toggle Switch is placed inside a table or another similar pattern, it is possible to rely on other UI elements, ie. a table header or a heading element, to convey the purpose of the switch. In such cases it is still required to pass the label prop but it should then be combined with the hideLabel prop.

If further context is needed the aria-describedby attribute could be used in the same manner.

ExamplesPermalink to: Examples

DefaultPermalink to: Default

import { ToggleSwitch } from "@peakon/bedrock/react/form";

<ToggleSwitch label="Settings" />

DisabledPermalink to: Disabled

The disabled state on the Toggle Switch is used when an option is unavailable, either due to system setting, admin choice or a previous choice made by the user themselves. When using a disabled Toggle Switch be sure to inform the user why it's disabled.

import { ToggleSwitch } from "@peakon/bedrock/react/form";
    
<ToggleSwitch
  label="Setting"
  disabled
/>

LockedPermalink to: Locked

A locked Toggle Switch can appear if the user doesn't have the correct rights or the system settings is preventing them from toggling the switch. When using a locked Toggle Switch be sure to inform the user why it's disabled.

import { ToggleSwitch } from "@peakon/bedrock/react/form";
    
<ToggleSwitch
  label="Setting"
  locked
/>

Hide LabelPermalink to: Hide Label

import { ToggleSwitch } from "@peakon/bedrock/react/form";

<table>
  <tbody>
    <tr>
      <td>
        Comments
      </td>
      <td>
        <ToggleSwitch label="Comments" hideLabel />
      </td>
    </tr>
    <tr>
      <td>Direct messages</td>
      <td>
        <ToggleSwitch label="Direct messages" hideLabel />
      </td>
    </tr>
    <tr>
      <td>Event updates</td>
      <td>
        <ToggleSwitch label="Event updates" hideLabel />
      </td>
    </tr>
    <tr>
      <td>Shares</td>
      <td>
        <ToggleSwitch label="Shares" hideLabel />
      </td>
    </tr>
  </tbody>
</table>

With descriptionPermalink to: With description

To provide the user with more context it is possible to add descriptive text.

import { ToggleSwitch } from "@peakon/bedrock/react/form";
    
<ToggleSwitch label="Setting" description="This is a description." />

ControlledPermalink to: Controlled

You can a Toggle Switch controlled with the checked and onChange props.

import React, { useState } from "react";
import { ToggleSwitch } from "@peakon/bedrock/react/form";

const [isToggled, setIsToggled] = useState<boolean>(false);

<ToggleSwitch
  label="Settings"
  checked={isToggled}
  onChange={(event) => setIsToggled(event.target.checked)}
/>

Props tablePermalink to: Props table

Props extend from the HTML input element(external link), with the omission of className, style, type, aria-labelledby and aria-label.

RelatedPermalink to: Related

• Component: Fieldset
• Component: Checkbox
• Component: Radio Button
• Component: Toggle Group

ReferencesPermalink to: References

• Norman Nielsen Group: Toggle-Switch Guidelines(external link)