# Toggle

**A button that toggles between pressed and unpressed.**

**Reference:** [View Source](https://github.com/jramke/fluid-primitives/tree/main/Resources/Private/Primitives/Toggle) · [Zag.js Docs](https://zagjs.com/components/react/toggle)

**ToggleExamples.html**

```html
<ui:toggle.root variant="outline" aria-label="Toggle bold" class="font-bold">B</ui:toggle.root>

```

## Features

- Renders a native `<button>` with `aria-pressed`, toggled with <kbd>Space</kbd> and <kbd>Enter</kbd>
- Can be pressed by default and disabled
- Optional indicator part that follows the pressed state
- For a set of related toggles, see [Toggle Group](/docs/components/toggle-group.md)

## Anatomy

```html
<primitives:toggle.root>
    <primitives:toggle.indicator />
</primitives:toggle.root>
```

## Installation

```bash
typo3 ui:add toggle
```

Or copy the files manually from GitHub (https://github.com/jramke/fluid-primitives/tree/main/Resources/Private/Registry/Toggle) into your project.

Read more about installing [Components and Primitives](/docs/core-concepts/primitives.md).

## Examples

### Default Pressed

Set the toggle to be pressed by default.

**ToggleExamples.html**

```html
<ui:toggle.root variant="outline" aria-label="Toggle italic" defaultPressed="{true}" class="italic">I</ui:toggle.root>

```

### Disabled

Prevent the toggle from being pressed.

**ToggleExamples.html**

```html
<div class="flex gap-2">
    <ui:toggle.root variant="outline" aria-label="Toggle underline" disabled="{true}" class="underline">U</ui:toggle.root>
    <ui:toggle.root variant="outline" aria-label="Toggle strikethrough" disabled="{true}" defaultPressed="{true}" class="line-through">S</ui:toggle.root>
</div>

```

### Indicator

The indicator carries the same `data-pressed` and `data-disabled` attributes as the root, so it can show the state of the toggle without any extra markup.

**ToggleExamples.html**

```html
<ui:toggle.root variant="outline">
    <ui:toggle.indicator class="size-2 rounded-full bg-muted-foreground/40 transition-colors data-[pressed]:bg-primary" />
    Notifications
</ui:toggle.root>

```

## API Reference

### toggle.root

Provides the pressed state and toggles it on click. Renders a `<button>` element.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `defaultPressed` | `boolean` | No | `false` | The initial pressed state of the toggle when rendered. Use when you don't need to control the pressed state of the toggle. |
| `disabled` | `boolean` | No | `-` | Whether the toggle is disabled. |
| `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. |
| `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. |
| `rootId` | `string` | No | `-` | The root ID of the component, used for hydration and identification. |
| `ids` | `array` | No | `[]` | The IDs of of the component parts for composition. |
| `autoMount` | `boolean` | No | `true` | Whether the client initializes the component on its own. Set it to false to mount it yourself with `mount()` |
| `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. |

#### Rendered data attributes

| Attribute | Description |
| --- | --- |
| `data-toggle-root` | <uid> |
| `data-pressed` | Present when pressed |
| `data-disabled` | Present when disabled |

### toggle.indicator

Visual indicator of the pressed state, e.g. an icon or a dot. Renders a `<span>` element.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. |
| `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. |
| `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. |

#### Rendered data attributes

| Attribute | Description |
| --- | --- |
| `data-toggle-indicator` | <uid> |
| `data-disabled` | Present when disabled |
| `data-pressed` | Present when pressed |

### Machine JavaScript API

| Name | Type | Description |
| --- | --- | --- |
| `pressed` | `boolean` | Whether the toggle is pressed. |
| `disabled` | `boolean` | Whether the toggle is disabled. |
| `setPressed` | `(pressed: boolean) => void` | Sets the pressed state of the toggle. |
| `getRootState` | `() => RootState` | Returns the state of the toggle |
| `getRootProps` | `() => T["element"]` | Props for the root `button` element. |
| `getIndicatorProps` | `() => T["element"]` | Props for the optional visual indicator (e.g. icon) element. |

### Accessibility

| Key | Description |
| --- | --- |
| `Space` `Enter`  | Toggle the pressed state |