---
title: Toggle Button
description: Toggle Buttons allow users to toggle a selection on or off.
thumbnail:
  image: /previews/components/core/toggle-button.jpeg
  video: /previews/components/core/toggle-button.mp4
links:
  - label: Aria docs
    href: https://react-spectrum.adobe.com/react-aria/ToggleButton.html
  - label: Aria API Reference
    href: https://react-spectrum.adobe.com/react-aria/ToggleButton.html#props
  - label: Report an issue
    href: https://github.com/mehdibha/dotUI/issues/new/choose
  - label: Edit this page
    href: https://github.com/mehdibha/dotUI/tree/main/content/components/buttons/toggle-button.mdx?plain=1
---

<ComponentPreview
  name="core/toggle-button-default"
  preview={`<ToggleButton>
    <PinIcon />
  </ToggleButton>`}
/>

## Installation

<Tabs items={["CLI", "Manual"]}>
  <Tab value="CLI">
  
  ```package-install
npx dotui-cli@latest add toggle-button
```

  </Tab>
  <Tab value="manual">
  
    <Steps>
      <Step>Install the following dependencies:</Step>

    ```package-install
    react-aria-components
    ```

      <Step>Copy and paste the following code into your project.</Step>
      <ComponentSource name="core/toggle-button" />
      <Step>Update the import paths to match your project setup.</Step>
    </Steps>

  </Tab>
</Tabs>

## Usage

Toggle button allow users to toggle a selection on or off, for example, switching between two states or modes.<br />
They can have a label, an icon, or both. An icon is provided by passing an icon component as child to the `ToggleButton` or by using the `prefix` and `suffix` props. A visible label can be provided by passing a string as a child.

## Options

### Variants

Use the `variant` prop to control the visual style of the toggle button.
The default size is `"quiet"`.

<ComponentPreview
  name="core/toggle-button-variants"
  preview={`<ToggleButton variant="quiet"><PinIcon /></ToggleButton>
<ToggleButton variant="outline"><PinIcon /></ToggleButton>
<ToggleButton variant="accent"><PinIcon /></ToggleButton>`}
/>

### Sizes

Use the `size` prop to control the size of the toggle button.<br/>
The default size is `"md"`.

<ComponentPreview
  name="core/toggle-button-sizes"
  preview={`<ToggleButton size="sm"><PinIcon /></ToggleButton>
<ToggleButton size="md"><PinIcon /></ToggleButton>
<ToggleButton size="lg"><PinIcon /></ToggleButton>`}
/>

### Shapes

Use the `shape` prop to control the shape of the toggle button. The default shape is `"rectangle"`.<br/>
Icon-only toggle buttons should include an `aria-label`.

<ComponentPreview
  name="core/toggle-button-shapes"
  preview={`<ToggleButton shape="square"><PinIcon /></ToggleButton>
<ToggleButton shape="circular"><PinIcon /></ToggleButton>
<ToggleButton prefix={<PinIcon />} shape="rectangle">Pin</ToggleButton>`}
/>

### Disabled

Use the `isDisabled` prop to disable the toggle button.

<ComponentPreview
  name="core/toggle-button-disabled"
  preview={`<ToggleButton isDisabled><PinIcon /></ToggleButton>`}
/>

## Uncontrolled

Use the `defaultSelected` to set the initial state of the toggle button.

<ComponentPreview
  name="core/toggle-button-uncontrolled"
  preview={`<ToggleButton defaultSelected><PinIcon /></ToggleButton>`}
/>

## Controlled

Use the `isSelected` and `onChange` props to control the state of the toggle button.

<ComponentPreview
  name="core/toggle-button-controlled"
  preview={`const [isSelected, setSelected] = React.useState(true);
  return (
    <ToggleButton isSelected={isSelected} onChange={setSelected}>
      <PinIcon className="rotate-45" />
    </ToggleButton>
  );`}
/>

## API Reference

| Prop              | Type                                                                                                      | Default    | Description                                                                                                 |
| ----------------- | --------------------------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------- |
| `variant`         | `"quiet" \| "outline" \| "accent"`                                                                        | `"quiet"`  | The visual style of the button.                                                                             |
| `size`            | `"sm" \| "md" \| "lg"`                                                                                    | `"md"`     | The size of the button.                                                                                     |
| `shape`           | `"rectangle" \| "square" \| "circle"`                                                                     | `"square"` | The visual shape of the button.                                                                             |
| `prefix`          | `React.ReactNode`                                                                                         | -          | A visual to display before the button text.                                                                 |
| `suffix`          | `React.ReactNode`                                                                                         | -          | A visual to display after the button text.                                                                  |
| `isSelected`      | `boolean`                                                                                                 | -          | Whether the element should be selected (controlled).                                                        |
| `defaultSelected` | `boolean`                                                                                                 | -          | Whether the element should be selected (uncontrolled).                                                      |
| `isDisabled`      | `boolean`                                                                                                 | -          | Whether the button is disabled.                                                                             |
| `autoFocus`       | `boolean`                                                                                                 | -          | Whether the element should receive focus on render.                                                         |
| `type`            | `'button' \| 'submit' \| 'reset'`                                                                         | -          | The behavior of the button when used in an HTML form.                                                       |
| `children`        | `ReactNode \| (values: ToggleButtonRenderProps & {defaultChildren: ReactNode \| undefined}) => ReactNode` | -          | The children of the component. A function may be provided to alter the children based on component state.   |
| `className`       | `string`                                                                                                  | -          | The CSS className for the element.                                                                          |
| `style`           | `CSSProperties \| (values: ToggleButtonRenderProps & {defaultStyle: CSSProperties}) => CSSProperties`     | -          | The inline style for the element. A function may be provided to compute the style based on component state. |

| Event           | Type                              | Description                                                                                                             |
| --------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `onChange`      | `(isSelected: boolean) => void`   | Handler that is called when the element's selection state changes.                                                      |
| `onPress`       | `(e: PressEvent) => void`         | Handler that is called when the press is released over the target.                                                      |
| `onPressStart`  | `(e: PressEvent) => void`         | Handler that is called when a press interaction starts.                                                                 |
| `onPressEnd`    | `(e: PressEvent) => void`         | Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.     |
| `onPressChange` | `(isPressed: boolean) => void`    | Handler that is called when the press state changes.                                                                    |
| `onPressUp`     | `(e: PressEvent) => void`         | Handler that is called when a press is released over the target, regardless of whether it started on the target or not. |
| `onFocus`       | `(e: FocusEvent<Target>) => void` | Handler that is called when the element receives focus.                                                                 |
| `onBlur`        | `(e: FocusEvent<Target>) => void` | Handler that is called when the element loses focus.                                                                    |
| `onFocusChange` | `(isFocused: boolean) => void`    | Handler that is called when the element's focus status changes.                                                         |
| `onKeyDown`     | `(e: KeyboardEvent) => void`      | Handler that is called when a key is pressed.                                                                           |
| `onKeyUp`       | `(e: KeyboardEvent) => void`      | Handler that is called when a key is released.                                                                          |
| `onHoverStart`  | `(e: HoverEvent) => void`         | Handler that is called when a hover interaction starts.                                                                 |
| `onHoverEnd`    | `(e: HoverEvent) => void`         | Handler that is called when a hover interaction ends.                                                                   |
| `onHoverChange` | `(isHovering: boolean) => void`   | Handler that is called when the hover state changes.                                                                    |

| Data attribute         | Description                                                    |
| ---------------------- | -------------------------------------------------------------- |
| `[data-selected]`      | Whether the button is currently selected.                      |
| `[data-hovered]`       | Whether the button is currently hovered with a mouse.          |
| `[data-pressed]`       | Whether the button is currently in a pressed state.            |
| `[data-focused]`       | Whether the button is focused, either via a mouse or keyboard. |
| `[data-focus-visible]` | Whether the button is keyboard focused.                        |
| `[data-disabled]`      | Whether the button is disabled.                                |

## Accessibility

### Keyboard interactions

| Key     | Description                       |
| ------- | --------------------------------- |
| `Space` | Activates/deactivates the toggle. |
| `Enter` | Activates/deactivates the toggle. |
