---
title: Toggle
description: "`Toggle` is a component that has two states: on or off."
links:
  - style: https://github.com/yamada-ui/yamada-ui/tree/main/packages/react/src/components/toggle/toggle.style.ts
  - source: https://github.com/yamada-ui/yamada-ui/tree/main/packages/react/src/components/toggle
  - storybook: https://yamada-ui.github.io/yamada-ui?path=/story/components-toggle--basic
---

```tsx
<Toggle icon={<BoldIcon />} aria-label="Toggle bold" />
```

## Usage

```ts
import { Toggle, ToggleGroup } from "@yamada-ui/react"
```

```ts
import { Toggle, ToggleGroup } from "@/components/ui"
```

```ts
import { Toggle, ToggleGroup } from "@workspaces/ui"
```

```tsx
<Toggle />
```

```tsx
<ToggleGroup.Root>
  <ToggleGroup.Item />
</ToggleGroup.Root>
```

### With Text

```tsx
<Toggle px="4">
  <ItalicIcon />
  <Text as="span" fontSize="md">
    Italic
  </Text>
</Toggle>
```

### Change Variant

```tsx
<Wrap gap="md">
  <For each={["ghost", "subtle", "surface", "outline", "solid"]}>
    {(variant) => (
      <Toggle
        key={variant}
        icon={<BoldIcon />}
        aria-label="Toggle bold"
        variant={variant}
      />
    )}
  </For>
</Wrap>
```

### Change Size

```tsx
<Wrap gap="md" alignItems="flex-start">
  <For each={["xs", "sm", "md", "lg", "xl"]}>
    {(size) => (
      <Toggle
        key={size}
        icon={<BoldIcon />}
        aria-label="Toggle bold"
        size={size}
      />
    )}
  </For>
</Wrap>
```

### Change Color Scheme

```tsx
<Wrap gap="md">
  <For each={["success", "warning"]}>
    {(colorScheme) => (
      <Toggle
        key={colorScheme}
        colorScheme={colorScheme}
        aria-label="Toggle bold"
        icon={<BoldIcon />}
      />
    )}
  </For>
</Wrap>
```

### Change Shape

To change the shape, set the `rounded` prop.

```tsx
<Wrap gap="md">
  <For each={["ghost", "subtle", "surface", "outline", "solid"]}>
    {(variant) => (
      <Toggle
        key={variant}
        icon={<BoldIcon />}
        aria-label="Toggle bold"
        variant={variant}
        fullRounded
      />
    )}
  </For>
</Wrap>
```

### Disable

To disable, set `disabled` to `true`.

```tsx
<Wrap gap="md">
  <For each={["ghost", "subtle", "surface", "outline", "solid"]}>
    {(variant) => (
      <Toggle
        key={variant}
        icon={<BoldIcon />}
        aria-label="Toggle bold"
        variant={variant}
        disabled
      />
    )}
  </For>
</Wrap>
```

### Read-Only

To read-only, set `readOnly` to `true`.

```tsx
<Wrap gap="md">
  <For each={["ghost", "subtle", "surface", "outline", "solid"]}>
    {(variant) => (
      <Toggle
        key={variant}
        icon={<BoldIcon />}
        aria-label="Toggle bold"
        variant={variant}
        readOnly
      />
    )}
  </For>
</Wrap>
```

### Invalid

To set invalid state, set `invalid` to `true`.

```tsx
<Wrap gap="md">
  <For each={["ghost", "subtle", "surface", "outline", "solid"]}>
    {(variant) => (
      <Toggle
        key={variant}
        icon={<BoldIcon />}
        aria-label="Toggle bold"
        variant={variant}
        invalid
      />
    )}
  </For>
</Wrap>
```

### Change Invalid Border Color

To change the border color, set `errorBorderColor` to the color.

```tsx
<Toggle
  aria-label="Toggle bold"
  errorBorderColor="orange.500"
  icon={<BoldIcon />}
  defaultChecked
  invalid
/>
```

### Control

```tsx
const [checked, setChecked] = useState<boolean>(false)

return (
  <Toggle
    icon={<BoldIcon />}
    aria-label="Toggle bold"
    checked={checked}
    onChange={setChecked}
  />
)
```

### Grouping

```tsx
<ToggleGroup.Root>
  <ToggleGroup.Item value="bold" icon={<BoldIcon />} aria-label="Toggle bold" />
  <ToggleGroup.Item
    value="italic"
    icon={<ItalicIcon />}
    aria-label="Toggle italic"
  />
  <ToggleGroup.Item
    value="underline"
    icon={<UnderlineIcon />}
    aria-label="Toggle underline"
  />
</ToggleGroup.Root>
```

For multiple selections, set `value` or `defaultValue` to an array.

```tsx
const [value, setValue] = useState<string[]>([])

return (
  <ToggleGroup.Root value={value} onChange={setValue}>
    <ToggleGroup.Item
      value="bold"
      icon={<BoldIcon />}
      aria-label="Toggle bold"
    />
    <ToggleGroup.Item
      value="italic"
      icon={<ItalicIcon />}
      aria-label="Toggle italic"
    />
    <ToggleGroup.Item
      value="underline"
      icon={<UnderlineIcon />}
      aria-label="Toggle underline"
    />
  </ToggleGroup.Root>
)
```

## Props

### Toggle

| Prop               | Default    | Type                                                                                                                                                              | Description                                                                |
| ------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `as`               | -          | `As`                                                                                                                                                              | The HTML element to render.                                                |
| `asChild`          | -          | `boolean`                                                                                                                                                         | Merges its props onto its immediate child.                                 |
| `css`              | -          | `CSSObject \| CSSObject[]`                                                                                                                                        | The CSS object.                                                            |
| `colorScheme`      | -          | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...`                                         | Set color scheme variables.                                                |
| `size`             | `"md"`     | `"2xl" \| "lg" \| "md" \| "sm" \| "xl" \| "xs"`                                                                                                                   | The size of the component.                                                 |
| `variant`          | `"ghost"`  | `"ghost" \| "outline" \| "solid" \| "subtle" \| "surface" ...`                                                                                                    | The variant of the component.                                              |
| `active`           | `false`    | `boolean`                                                                                                                                                         | If `true`, the button is represented as active.                            |
| `checked`          | -          | `boolean`                                                                                                                                                         | If `true`, the toggle button will be checked.                              |
| `disabled`         | `false`    | `boolean`                                                                                                                                                         | If `true`, the button is disabled.                                         |
| `disableRipple`    | `false`    | `boolean`                                                                                                                                                         | If `true`, disable ripple effects when pressing a element.                 |
| `errorBorderColor` | -          | `"-moz-initial" \| "ActiveBorder" \| "ActiveCaption" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" \| "amber.400" \| "amber.50" \| "amber.500" ...` | The border color when the input is invalid.                                |
| `fullRounded`      | `false`    | `boolean`                                                                                                                                                         | If true, the toggle button is full rounded. Else, it'll be slightly round. |
| `icon`             | -          | `string \| number \| bigint \| boolean \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal \| Promise<...>`      | The icon to be used in the button.                                         |
| `invalid`          | `false`    | `boolean`                                                                                                                                                         | If `true`, the field will be invalid.                                      |
| `loading`          | `false`    | `boolean`                                                                                                                                                         | If `true`, the loading state of the button is represented.                 |
| `onChange`         | -          | `(checked: boolean) => void`                                                                                                                                      | The callback invoked when checked state changes.                           |
| `readOnly`         | `false`    | `boolean`                                                                                                                                                         | If `true`, the field will be readonly.                                     |
| `required`         | `false`    | `boolean`                                                                                                                                                         | If `true`, the field will be required.                                     |
| `type`             | `"button"` | `"button" \| "reset" \| "submit"`                                                                                                                                 | The type of button. Accepts `button`, `reset`, or `submit`.                |
| `value`            | -          | `Y`                                                                                                                                                               | The value of the toggle button.                                            |

### ToggleGroup.Root

| Prop           | Default        | Type                                                                                                                                                 | Description                                                                                              |
| -------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `as`           | -              | `As`                                                                                                                                                 | The HTML element to render.                                                                              |
| `asChild`      | -              | `boolean`                                                                                                                                            | Merges its props onto its immediate child.                                                               |
| `css`          | -              | `CSSObject \| CSSObject[]`                                                                                                                           | The CSS object.                                                                                          |
| `colorScheme`  | -              | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...`                            | Set color scheme variables.                                                                              |
| `size`         | `"md"`         | `"2xl" \| "lg" \| "md" \| "sm" \| "xl" \| "xs"`                                                                                                      | The size of the component.                                                                               |
| `variant`      | `"ghost"`      | `"ghost" \| "outline" \| "solid" \| "subtle" \| "surface" ...`                                                                                       | The variant of the component.                                                                            |
| `align`        | -              | `"-moz-initial" \| "baseline" \| "center" \| "end" \| "flex-end" \| "flex-start" \| "inherit" \| "initial" \| "normal" \| "revert-layer" ...`        | The CSS `align-items` property.                                                                          |
| `attached`     | `false`        | `boolean`                                                                                                                                            | If `true`, the borderRadius of button that are direct children will be altered to look flushed together. |
| `basis`        | -              | `"-moz-fit-content" \| "-moz-initial" \| "-moz-max-content" \| "-moz-min-content" \| "-webkit-auto" \| "0.5" \| "1.5" \| "1" \| "1/12" \| "1/2" ...` | The CSS `flex-basis` property.                                                                           |
| `defaultValue` | -              | `Y extends any[] ? Y : undefined \| Y`                                                                                                               | The initial value of the toggle button group.                                                            |
| `direction`    | -              | `"-moz-initial" \| "column-reverse" \| "column" \| "inherit" \| "initial" \| "revert-layer" \| "revert" \| "row-reverse" \| "row" \| "unset" ...`    | The CSS `flex-direction` property.                                                                       |
| `disabled`     | `false`        | `boolean`                                                                                                                                            | If `true`, all wrapped toggle button will be disabled.                                                   |
| `fullRounded`  | `false`        | `boolean`                                                                                                                                            | If true, the toggle button is full rounded. Else, it'll be slightly round.                               |
| `grow`         | `false`        | `boolean`                                                                                                                                            | If `true`, the children will grow to fill the available space.                                           |
| `justify`      | -              | `"-moz-initial" \| "center" \| "end" \| "flex-end" \| "flex-start" \| "inherit" \| "initial" \| "left" \| "normal" \| "revert-layer" ...`            | The CSS `justify-content` property.                                                                      |
| `onChange`     | -              | `(value: Y extends any[] ? Y : undefined \| Y) => void`                                                                                              | The callback fired when any children toggle button is selected or unselected.                            |
| `orientation`  | `"horizontal"` | `"horizontal" \| "vertical"`                                                                                                                         | The orientation of the group.                                                                            |
| `readOnly`     | `false`        | `boolean`                                                                                                                                            | If `true`, all wrapped toggle button will be readonly.                                                   |
| `shrink`       | -              | `"-moz-initial" \| "inherit" \| "initial" \| "revert-layer" \| "revert" \| "unset" \| number & {} ...`                                               | The CSS `flex-shrink` property.                                                                          |
| `stacking`     | -              | `"first-on-top" \| "last-on-top"`                                                                                                                    | The stacking order of the group.                                                                         |
| `value`        | -              | `Y extends any[] ? Y : undefined \| Y`                                                                                                               | The value of the toggle button group.                                                                    |
| `wrap`         | -              | `"-moz-initial" \| "inherit" \| "initial" \| "nowrap" \| "revert-layer" \| "revert" \| "unset" \| "wrap-reverse" \| "wrap" ...`                      | The CSS `flex-wrap` property.                                                                            |

### ToggleGroup.Item

| Prop               | Default    | Type                                                                                                                                                              | Description                                                                |
| ------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `as`               | -          | `As`                                                                                                                                                              | The HTML element to render.                                                |
| `asChild`          | -          | `boolean`                                                                                                                                                         | Merges its props onto its immediate child.                                 |
| `css`              | -          | `CSSObject \| CSSObject[]`                                                                                                                                        | The CSS object.                                                            |
| `colorScheme`      | -          | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...`                                         | Set color scheme variables.                                                |
| `size`             | `"md"`     | `"2xl" \| "lg" \| "md" \| "sm" \| "xl" \| "xs"`                                                                                                                   | The size of the component.                                                 |
| `variant`          | `"ghost"`  | `"ghost" \| "outline" \| "solid" \| "subtle" \| "surface" ...`                                                                                                    | The variant of the component.                                              |
| `active`           | `false`    | `boolean`                                                                                                                                                         | If `true`, the button is represented as active.                            |
| `checked`          | -          | `boolean`                                                                                                                                                         | If `true`, the toggle button will be checked.                              |
| `disabled`         | `false`    | `boolean`                                                                                                                                                         | If `true`, the button is disabled.                                         |
| `disableRipple`    | `false`    | `boolean`                                                                                                                                                         | If `true`, disable ripple effects when pressing a element.                 |
| `errorBorderColor` | -          | `"-moz-initial" \| "ActiveBorder" \| "ActiveCaption" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" \| "amber.400" \| "amber.50" \| "amber.500" ...` | The border color when the input is invalid.                                |
| `fullRounded`      | `false`    | `boolean`                                                                                                                                                         | If true, the toggle button is full rounded. Else, it'll be slightly round. |
| `icon`             | -          | `string \| number \| bigint \| boolean \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal \| Promise<...>`      | The icon to be used in the button.                                         |
| `invalid`          | `false`    | `boolean`                                                                                                                                                         | If `true`, the field will be invalid.                                      |
| `loading`          | `false`    | `boolean`                                                                                                                                                         | If `true`, the loading state of the button is represented.                 |
| `onChange`         | -          | `(checked: boolean) => void`                                                                                                                                      | The callback invoked when checked state changes.                           |
| `readOnly`         | `false`    | `boolean`                                                                                                                                                         | If `true`, the field will be readonly.                                     |
| `required`         | `false`    | `boolean`                                                                                                                                                         | If `true`, the field will be required.                                     |
| `type`             | `"button"` | `"button" \| "reset" \| "submit"`                                                                                                                                 | The type of button. Accepts `button`, `reset`, or `submit`.                |
| `value`            | -          | `Y`                                                                                                                                                               | The value of the toggle button.                                            |

## Accessibility

Currently, this section is being updated due to the migration of v2.