---
name: Toggle
menu: 'Components: UI'
route: /components/ui/toggle
---

# Toggle

Toggle switches things on and off.

import {
  Playground,
  Props,
} from 'docz'
import { Toggle } from './Toggle'

## Basic Usage

To implement the Toggle component, you need to import it first:

```js
import { Toggle } from '@react-ui-org/react-ui';
```

And use it:

<Playground>
  {() => {
    const [studioQuality, setStudioQuality] = React.useState(true);
    return (
      <Toggle
        changeHandler={() => setStudioQuality(!studioQuality)}
        checked={studioQuality}
        id="my-toggle"
        label="Listen in studio quality"
      />
    );
  }}
</Playground>

See [API](#api) for all available options.

## General Guidelines

- Use the toggle only for boolean (true/false) input **with an immediate effect
  (without confirmation)**. To toggle things on or off in forms that require to
  be submitted by a button, use rather the
  [CheckboxField](/components/ui/checkbox-field) component.

- **Use positive wording for the toggle label,** so that it's clear what will
  happen when the user turns on the toggle. Avoid negations such as “Don't send
  me any emails” which would mean that the user needs to turn the toggle **on**
  in order for something **not** to happen.

- Only make the Toggle's label invisible when there is **another visual clue**
  to guide users through using the input.

- When a short label is not enough, use **help texts to guide users** before
  they enter anything.

- Use **clear, calm error messages** when there's a problem with what they
  entered.

- The toggle is designed for **switching things on and off.** Don't use it to
  switch between two different things that cannot be described as on or off
  using a single label, eg. different viewing modes. In such cases, consider
  using the [ButtonGroup](/components/ui/button-group) component.

## Help Text

You may provide an additional help text to clarify what will be the impact of
turning the toggle on or off.

<Playground>
  {() => {
    const [studioQuality, setStudioQuality] = React.useState(true);
    return (
      <Toggle
        changeHandler={() => setStudioQuality(!studioQuality)}
        checked={studioQuality}
        description={
          'Unrivaled audio quality. Uses the MQA audio format. '
          + 'Transfers a lot of data.'
        }
        id="my-toggle-with-helper-text"
        label="Listen in studio quality"
      />
    );
  }}
</Playground>

## Label Options

In some cases, it may be convenient to visually hide the toggle label. The label
remains accessible to assistive technologies.

<Playground>
  {() => {
    const [studioQuality, setStudioQuality] = React.useState(true);
    return (
      <Toggle
        changeHandler={() => setStudioQuality(!studioQuality)}
        checked={studioQuality}
        id="my-toggle-with-invisible-label"
        isLabelVisible={false}
        label="You cannot see this"
      />
    );
  }}
</Playground>

It's also possible to display the label before the input:

<Playground>
  {() => {
    const [studioQuality, setStudioQuality] = React.useState(true);
    return (
      <Toggle
        changeHandler={() => setStudioQuality(!studioQuality)}
        checked={studioQuality}
        id="my-toggle-with-label-before-input"
        label="Listen in studio quality"
        labelPosition="before"
      />
    );
  }}
</Playground>

## States

### Validation States

Validation states visually present the result of validation of the input. You
should always **provide a help text for states other than valid** so users know
what happened and what action they should take or what options they have.

<Playground>
  {() => {
    const [studioQuality, setStudioQuality] = React.useState(true);
    return (
      <>
        <Toggle
          changeHandler={() => setStudioQuality(!studioQuality)}
          checked={studioQuality}
          id="my-toggle-valid"
          label="Listen in studio quality"
          validationState="valid"
        />
        <Toggle
          changeHandler={() => setStudioQuality(!studioQuality)}
          checked={studioQuality}
          description={
            'Looks like you are connected over cellular network. '
            + 'Please make sure you know what you are doing.'
          }
          id="my-toggle-warning"
          label="Listen in studio quality"
          validationState="warning"
        />
        <Toggle
          changeHandler={() => setStudioQuality(!studioQuality)}
          checked={studioQuality}
          error="Please upgrade your plan to make this option available."
          id="my-toggle-invalid"
          label="Listen in studio quality"
          validationState="invalid"
        />
      </>
    );
  }}
</Playground>

### Disabled State

Disabled state makes the input unavailable.

<Playground>
  <Toggle label="Disabled toggle" id="my-toggle-disabled" disabled />
  <Toggle
    label="Disabled toggle, checked"
    id="my-toggle-checked-disabled"
    disabled
    checked
  />
</Playground>

## API

In addition to the options below, you can add any custom attributes that do not
interfere with the API, and they will be passed to the `input` HTML element.
This is useful mainly to improve component's accessibility.

<Props of={Toggle} />

---

Next: [CTA →](/components/layout/cta)
