Toggle

Used as an alternative to the Checkbox for choosing between enabled and disabled states.

• View on Github
• View Core API
• View on Figma

Import

import { Toggle, ToggleButton } from '@pluralsight/react'

Anatomy

1. Wrapper
2. Label (optional)
3. Container
4. Input
5. Track
6. Thumb
7. Label (optional)

Usage

Basic Toggle

Result

Loading...

Live Editor

function BasicToggle() { const [checked, setChecked] = useState(false) function handleChange(e) { setChecked(e.target.checked) } return ( <FormControlProvider> <Toggle> <Label htmlFor="notifications">Sign up for notifications</Label> <ToggleButton checked={checked} id="notifications" name="notifications" onChange={handleChange} /> </Toggle> </FormControlProvider> ) }

function BasicToggle() {
  const [checked, setChecked] = useState(false)

  function handleChange(e) {
    setChecked(e.target.checked)
  }

  return (
    <FormControlProvider>
      <Toggle>
        <Label htmlFor="notifications">Sign up for notifications</Label>
        <ToggleButton
          checked={checked}
          id="notifications"
          name="notifications"
          onChange={handleChange}
        />
      </Toggle>
    </FormControlProvider>
  )
}

Sizes

Result

Loading...

Live Editor

function ToggleSizes() { const [checked, setChecked] = useState(false) function handleChange(e) { setChecked(e.target.checked) } return ( <form> <FormControlProvider> <Toggle> <Label htmlFor="medium">Medium size</Label> <ToggleButton checked={checked} id="medium" name="medium" onChange={handleChange} pandoSize="m" /> </Toggle> </FormControlProvider> <br /> <FormControlProvider> <Toggle> <ToggleButton checked={checked} id="small" name="small" onChange={handleChange} pandoSize="s" /> <Label htmlFor="small">Small size</Label> </Toggle> </FormControlProvider> </form> ) }

function ToggleSizes() {
  const [checked, setChecked] = useState(false)

  function handleChange(e) {
    setChecked(e.target.checked)
  }

  return (
    <form>
      <FormControlProvider>
        <Toggle>
          <Label htmlFor="medium">Medium size</Label>
          <ToggleButton
            checked={checked}
            id="medium"
            name="medium"
            onChange={handleChange}
            pandoSize="m"
          />
        </Toggle>
      </FormControlProvider>

      <br />

      <FormControlProvider>
        <Toggle>
          <ToggleButton
            checked={checked}
            id="small"
            name="small"
            onChange={handleChange}
            pandoSize="s"
          />
          <Label htmlFor="small">Small size</Label>
        </Toggle>
      </FormControlProvider>
    </form>
  )
}

States

Checked

Disabled

Invalid

Read only

Required (required)

Customizing

There are 3 ways to customize the Toggle component.

1. Unused Classes

Each component layer of the Toggle has a unused class name that can be utilized in your local CSS to customize the Toggle at any level.

1. pando-toggle-container: The container element of the Toggle.
2. pando-toggle-input: The input element of the Toggle.
3. pando-toggle-control: The control element of the Toggle.
4. pando-toggle-track: The track element of the Toggle.
5. pando-toggle-thumb: The thumb element of the Toggle.
6. pando-toggle-wrapper: The wrapper element of the Toggle

2. Passing a className prop

You can pass a className prop to the Toggle component to customize the Toggle. This is useful if your project uses CSS Modules or a CSS-in-JS library like Emotion.

Example of using CSS Modules to customize the Toggle.

import customStyles from './customStyles.module.css'

function CustomToggle(props) {
  return <Toggle className={customStyles.custom} {...props} />
}

function CustomToggleButton(props) {
  return <ToggleButton className={customStyles.custom} {...props} />
}

3. Ejected Toggle

For a low-level "ejected" approach, you can use the Headless-styles API to customize the Toggle however you prefer while keeping the accessibility behavior.

import {
  getSwitchProps,
  getSwitchWrapperProps,
} from '@pluralsight/headless-styles'

To learn more about the Headless-styles API, check out the Headless-styles documentation.

Behavior

Layout

Do use multiple Toggles in a vertical list.

Don't use multiple Toggles in a single row.

Do provide a Label with a Toggle.

Don't use a Toggle inline without a Label. Instead use a hidden Label.

Usage

Do use a Toggle for giving users an way to opt-in to an optional feature.

Don't use a Toggle for collecting consent. Instead us a Checkbox.

API

Toggle: FC<ToggleProps>

type ToggleProps = HTMLAttributes<HTMLDivElement>

Parameters

1. Any props that can be passed to a div element.

ToggleButton: FC<ToggleButtonProps>

interface ToggleButtonProps extends InputHTMLAttributes<HTMLInputElement> {
  checked: boolean
  id: string
  name: string
  pandoSize?: 's' | 'm'
}

Parameters

1. Any props that can be passed to an input element.
2. checked: Whether the Toggle is checked or not.
3. id: The id of the Toggle.
4. name: The name of the Toggle.
5. pandoSize: The size of the Toggle.

Size Mapping

Toggle size rules.

{
  s: 'Use in condensed areas where the default size is too large.',
  m: 'Should be used in most, if not all cases.'
}

Accessibility

The Pando Toggle is fully accessible and screen-readable through the following features:

1. The aria-invalid attribute is set to true when the input is invalid.
2. The aria-describedby attribute is set to the id of the FieldMessage or ErrorMessage that describes the input.
3. The aria-required attribute is set to true when the input is required.
4. The aria-disabled attribute is set to true when the input is disabled.
5. The aria-checked attribute is set to true when the input is checked.
6. The aria-checked attribute is set to mixed when the input is indeterminate.
7. The aria-hidden attribute is set to true on the input control and icon to hide it from screen readers.