## 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

Provide a label for the toggle to make it accessible and valid markup.

label

If composing a custom label, pass in the ID of the custom label that the button should be labelled by.

ariaLabelledBy

ID used for the internal label element when `label` is set.

Size options for the toggle. Defaults to `medium`.

size

Determines if the toggle should be toggled. Use along with the `onClick` prop when controlling the state of the toggle. Defaults to `false`.

toggled

Determines if the toggle should be disabled and prevented from being interacted with. Defaults to `false`.

disabled

Called when a toggle is clicked/toggled. Use along with the `toggled` prop when controlling the state of the toggle.

onClick

block

Prop	Required	Description	Type
`label`	—	Provide a label for the toggle to make it accessible and valid markup.	string
`ariaLabelledBy`	—	If composing a custom label, pass in the ID of the custom label that the button should be labelled by.	string
`id`	—	ID used for the internal label element when label is set.	string
`size`	—	Size options for the toggle. Defaults to medium.	string
`toggled`	—	Determines if the toggle should be toggled. Use along with the onClick prop when controlling the state of the toggle. Defaults to false.	boolean
`disabled`	—	Determines if the toggle should be disabled and prevented from being interacted with. Defaults to false.	boolean
`onClick`	—	Called when a toggle is clicked/toggled. Use along with the toggled prop when controlling the state of the toggle.	(isToggled: boolean) => void
`block`	—	Makes the toggle fill its container.	false \| trueSupports responsive prop syntax