# Toggle

A button that is on or off, with aria-pressed.

```ehtml Example
import { Toggle } from "@elements/ui/toggle";
import { Icon } from "@elements/ui/icon";

<Toggle pressed={editor.bold} label="Bold"><Icon name="bold" /></Toggle>
<Toggle variant="outline" pressed={filters.starred}><Icon name="star" /> Starred</Toggle>
```

## Parts

| Part | What it is |
|---|---|
| `.toggle` | The button. Usable without the template with aria-pressed and data-state. |

## Attributes

| Attribute | Type | Default | Description |
|---|---|---|---|
| `pressed` | `boolean` (two-way) | `false` | On or off. Bind it to state; a press writes back. |
| `variant` | `"default" \| "outline"` | `"default"` | Quiet or bordered. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Height from the control tokens. |
| `label` | `string` | `""` | Accessible name (aria-label); required for an icon-only toggle. |
| `disabled` | `boolean` | `false` | Native disabled. |
| `class` | `string` | `""` | Extra classes on the button. |
| `attrs` | `Record<string, string \| number \| boolean \| undefined>` | `{}` | id, title, aria-\*, data-\*. |
| `onPressedChange` | `(pressed: boolean, details: ChangeDetails) => void` | `() => {}` | The user pressed it (not called for changes made in code). It runs before the change with details second (reason, event, cancel(), isCanceled); details.cancel() keeps the state. |

## Slots

| Slot | Content |
|---|---|
| `default` | An icon, text, or both. |

## Keyboard

| Keys | Action |
|---|---|
| `Space` | Turns it on or off. |
| `Enter` | Turns it on or off. |

## Data attributes

| Attribute | Values | On | Description |
|---|---|---|---|
| `data-state` | `"on" \| "off"` | button |  |
| `data-pressed` | present while pressed | button | The same state as data-state="on", as a presence attribute. |
| `data-disabled` | present while disabled | button |  |
| `data-variant` | `"default" \| "outline"` | button |  |
| `data-size` | `"sm" \| "md" \| "lg"` | button |  |

## Accessibility

- A native `<button type="button">` with aria-pressed, so it is announced as a toggle button with its state.
- Keep the label the same in both states; the pressed state carries the change.
- An icon-only toggle needs label.

## See also

- [Icon](icon): An inline stroke icon from the set the templates draw their own controls with, sized in pixels and colored by the text around it.
- [ButtonGroup](button-group): Related buttons, or an input and its buttons, joined into one control.
- [Input](input): A native text input in the theme's control chrome, with a two-way value.
- [InputGroup](input-group): An Input or Textarea with icons, text and buttons inside one box.
- [Textarea](textarea): A native multi-line input that grows with its content, between rows and maxRows.
- [Field](field): A label, a control, a description and an error wired together, with native validation that never moves the layout.