## Usage

Use the `<Toggle />` component for binary actions that occur immediately after the user "flips the switch".

```tsx live
<Toggle label="Living room light" />
```

### Guidelines

- For confirmation, use a `<Checkbox />` component instead of a toggle.
- When error handling is required, use a `<Checkbox />` or `<Radio />` component instead of a toggle.
- Examples of when to use a `<Toggle />` include, but not limited to:
  - Enable/disable modules
  - Show/hide additional options
  - Activate a mode (such as "dark mode") which takes immediate effect
  - Turn on/turn off settings

## Label

To make the toggle accessible and render valid markup, always provide a concise label that describes what will be switched on/off. The simplest way is using the `label` prop.

Alternatively, if you need to compose a custom label you can use the `ariaLabelledBy` prop to make it accessible. Read more on how to do this under [Custom label composition](#custom-label-composition).

NOTE: The `label` prop can not be used at the same time as the `ariaLabelledBy` prop.

## Controlled

The toggle can be uncontrolled or controlled. Use the `toggled` prop, along with `onClick` to take control of the state.

```tsx live
const [isToggled, setIsToggled] = useState(false);

return (
  <Flex flexDirection="column">
    <Toggle toggled={isToggled} onClick={setIsToggled} label="Controlled" />
    <ResponseBlock prefix="isToggled state:" value={JSON.stringify(isToggled)} />
  </Flex>
);
```

## Disabled

Use the `disabled` prop when the user shouldn't be able to manipulate the toggle.

```tsx live
<Flex gap="medium" flexDirection="column">
  <Toggle disabled label="Living room light" />
  <Toggle disabled toggled label="Living room light" />
</Flex>
```

## Size

There are two toggle sizes, `small` and `medium` (default). On smaller screens the toggle's tap (vertical) target area is increased to make the item easier to press.

```tsx live
<Flex gap="medium" flexDirection="column">
  <Toggle toggled size="small" label="Small" />
  <Toggle toggled label="Medium (default)" />
</Flex>
```

## Custom label composition

If you need to compose a custom label you can opt out of using the `label` prop. Instead, to make it accessible you need to pass in your custom label's `id` to the toggle's `ariaLabelledBy` prop. Below is a contrived example of how you can achieve a "clickable toggle card".

```tsx live
const [isToggled, setIsToggled] = useState(false);

return (
  <Flex
    gap="medium"
    backgroundColor="neutral"
    borderRadius="large"
    borderColor="neutralSubtle"
    borderWidth="thin"
    borderStyle="solid"
    padding="medium"
    onClick={() => setIsToggled((isToggled) => !isToggled)}
    className={css({
      '&:hover': {
        backgroundColor: backgroundColor.neutralSubtle,
        cursor: 'pointer',
      },
    })}
  >
    <Toggle ariaLabelledBy="custom-label-toggle" toggled={isToggled} />

    <Text id="custom-label-toggle" display="flex" flexDirection="column" fontWeight="medium">
      <Flex alignItems="center" gap="xxsmall">
        <span>Custom label</span>
        <CheckCircleIcon size="small" color="positive" />
      </Flex>
      <Text color="neutralSubtle" fontSize="small">
        Sub text
      </Text>
    </Text>
  </Flex>
);
```

A control that allows the user to perform a binary action (on/off).

Toggle

Accessibility

Responsive layouts

Tokens

Foundations

a11y

Accordion

Actions

AddressInput

AppLayout

Avatar

Badge

Blanket

Breadcrumbs

BulkActionBar

Button

Card

Checkbox

Core

DateDropdown

DateInput

Divider

EmptyState

Field

Fieldset

FileInput

Filtering

Flex

Grid

Heading

Icon

Illustration

Link

List

Loading

Modal

Notice

PageHeader

Pagination

PhoneInput

Popover

Radio

RailTrack

RichTextEditor

ScrollWrap

SearchInput

SelectDropdown

SelectInput

ShowMore

Table

Tabs

Text

TextAreaInput

TextInput

Toast

Tooltip

Utils

Utils - NextJS

Components

Forms

Search

Tables

Patterns

Introduction

Product tone and voice

Capitalisation

Date and time

Inclusive design

Content

Welcome to EDS

Start designing

Start developing

Contributing

Releases

The EDS way

Coding style guide

Guide to Pendo

Setting up the EDS repo

Creating a new component

Automated testing

PR and changeset process

Publishing snapshots

Publishing packages

Monorepo tools

Team resources