Skip to main content

Toggle

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

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

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

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

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.

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

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