# Toggle

## Overview

A pressable button that maintains an on/off state visually, similar to a keyboard key that stays pressed. Used in toolbars for formatting, view switching, and feature activation.

---

## When to Use

- Text formatting toolbars (Bold, Italic, Underline)
- View mode switches (List view / Grid view)
- Filter activation buttons that remain pressed when active

## When NOT to Use

- Immediate action triggers — use `<Button>` instead.
- Feature settings — use `<Switch>` or `<Checkbox>` for clearer semantics.

---

## Props

| Prop              | Type                         | Default     | Description                        |
| ----------------- | ---------------------------- | ----------- | ---------------------------------- |
| `pressed`         | `boolean`                    | —           | Controlled pressed state           |
| `defaultPressed`  | `boolean`                    | `false`     | Uncontrolled initial state         |
| `onPressedChange` | `(pressed: boolean) => void` | —           | Change handler                     |
| `variant`         | `'default' \| 'outline'`     | `'default'` | Visual style                       |
| `size`            | `'default' \| 'sm' \| 'lg'`  | `'default'` | Size preset                        |
| `disabled`        | `boolean`                    | `false`     | Disables interaction               |
| `aria-label`      | `string`                     | —           | **Required** for icon-only toggles |

---

## Examples

```tsx
import { Toggle } from 'xertica-ui/ui';
import { Bold } from 'lucide-react';

<Toggle aria-label="Bold">
  <Bold className="size-4" />
</Toggle>;
```

### Controlled

```tsx
const [bold, setBold] = useState(false);

<Toggle pressed={bold} onPressedChange={setBold} aria-label="Bold">
  <Bold className="size-4" />
</Toggle>;
```

---

## Related Components

- [`ToggleGroup`](./toggle-group.md) — Multiple related toggles with exclusion
- [`Switch`](./switch.md) — For settings toggles with clearer on/off semantics