## Overview [#overview]
The `Toggle` component is a button-like control for two-state actions such as formatting, view options, and compact toolbar settings. It owns the default and outline pressed states, so grouped toggles can reuse the same surface behavior.
## Usage [#usage]
```tsx
import { Toggle } from "@tilt-legal/cubitt-components/toggle";
```
```tsx
```
Sync pressed state with the URL by providing a `paramName`.
```tsx
Bold
```
## Examples [#examples]
### Default [#default]
Default toggles behave like ghost buttons until pressed.
```tsx
import { Toggle } from "@tilt-legal/cubitt-components/toggle";
import { TextBold } from "@tilt-legal/cubitt-icons/ui/outline";
export default function Example() {
return (
);
}
```
### Outline [#outline]
Use the outline variant when the toggle should carry a contextual bordered surface.
```tsx
import { Toggle } from "@tilt-legal/cubitt-components/toggle";
import { TextItalic } from "@tilt-legal/cubitt-icons/ui/outline";
export default function Example() {
return (
);
}
```
### With Text [#with-text]
Toggles can include both an icon and a short label.
```tsx
import { Toggle } from "@tilt-legal/cubitt-components/toggle";
import {
TextBold,
TextItalic,
} from "@tilt-legal/cubitt-icons/ui/outline";
export default function Example() {
return (
Bold
Italic
);
}
```
### Sizes [#sizes]
Toggles support `sm`, `md`, and `lg` sizes.
```tsx
import { Toggle } from "@tilt-legal/cubitt-components/toggle";
import {
TextBold,
TextItalic,
TextUnderline,
} from "@tilt-legal/cubitt-icons/ui/outline";
export default function Example() {
return (
);
}
```
### URL State [#url-state]
Use URL state when the pressed value should be shareable or restored on refresh.
```tsx
import { Toggle } from "@tilt-legal/cubitt-components/toggle";
import { TextBold } from "@tilt-legal/cubitt-icons/ui/outline";
export default function Example() {
return (
Bold
);
}
```
## API Reference [#api-reference]
### Toggle [#toggle]
| Prop | Type | Default | Description |
| ----------------- | ---------------------------- | ----------- | --------------------------------------------- |
| `pressed` | `boolean` | - | Controlled pressed state. |
| `defaultPressed` | `boolean` | `false` | Initial pressed state for uncontrolled usage. |
| `onPressedChange` | `(pressed: boolean) => void` | - | Called when the pressed state changes. |
| `disabled` | `boolean` | `false` | Disables the toggle. |
| `variant` | `"default" \| "outline"` | `"default"` | Visual style. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Toggle size. |
| `className` | `string` | - | Additional classes. |
| `children` | `React.ReactNode` | - | Toggle content. |
### URL State Props [#url-state-props]
| Prop | Type | Default | Description |
| --------------------- | ------------------------------------ | ------- | --------------------------------------------------------- |
| `paramName` | `string` | - | Search parameter name used for URL state. |
| `paramValue` | `boolean` | - | Controlled URL-backed value. |
| `onUrlValueChange` | `(pressed: boolean \| null) => void` | - | Called when the URL-backed value changes. |
| `paramClearOnDefault` | `boolean` | `true` | Removes the URL parameter when value matches the default. |
| `paramThrottle` | `number` | - | Throttles URL updates in milliseconds. |
| `paramDebounce` | `number` | - | Debounces URL updates in milliseconds. |
### Notes [#notes]
* Use `aria-label` for icon-only toggles.
* Use `pressed` and `onPressedChange` for controlled state.
* Use `ToggleGroup` when related toggles need coordinated keyboard navigation or shared selection state.