## Overview [#overview]
The **Toggle** component provides a pressable button that switches between active and inactive states, commonly used for toolbar actions, formatting options, or feature toggles. Built on Base UI primitives, it features customizable variants, sizes, and smooth transitions.
## Usage [#usage]
```tsx
import { Toggle } from "@tilt-legal/cubitt-components/primitives";
```
```tsx
```
Using Cubitt's URL-state hooks, you can sync the toggle state with the URL by providing a `paramName`:
```tsx
// Toggle state synced with ?bold=true
Bold
// Advanced options:
console.log('Toggle state:', pressed)}
aria-label="Toggle feature"
>
Feature
```
***
## Examples [#examples]
### Default [#default]
Basic toggle button with default styling.
```tsx
import { Toggle } from "@tilt-legal/cubitt-components/primitives";
import {
TextBold } from "@tilt-legal/cubitt-icons/ui/outline";
export default function Example() {
return (
);
}
```
### Outline Variant [#outline-variant]
Toggle with outlined styling.
```tsx
import { Toggle } from "@tilt-legal/cubitt-components/primitives";
import {
TextItalic } from "@tilt-legal/cubitt-icons/ui/outline";
export default function Example() {
return (
);
}
```
### With Text [#with-text]
Toggle buttons can include both icons and text labels.
```tsx
import { Toggle } from "@tilt-legal/cubitt-components/primitives";
import {
TextBold,
TextItalic } from "@tilt-legal/cubitt-icons/ui/outline";
export default function Example() {
return (
Bold
Italic
);
}
```
### Sizes [#sizes]
Toggles in different sizes.
```tsx
import { Toggle } from "@tilt-legal/cubitt-components/primitives";
import {
TextBold,
TextItalic,
TextUnderline } from "@tilt-legal/cubitt-icons/ui/outline";
export default function Example() {
return (
);
}
```
### URL State [#url-state]
Sync toggle state with the URL. Try toggling and refreshing the page.
```tsx
import { Toggle } from "@tilt-legal/cubitt-components/primitives";
import { TextBold } from "@tilt-legal/cubitt-icons/ui/outline";
export default function Example() {
return (
Bold
);
}
```
***
## API Reference [#api-reference]
### Toggle [#toggle]
A pressable button that maintains pressed/unpressed state.
| Prop | Type | Default | Description |
| ----------------- | ---------------------------- | ----------- | --------------------------------------------------------- |
| `pressed` | `boolean` | — | The controlled pressed state of the toggle. |
| `defaultPressed` | `boolean` | `false` | The default pressed state when uncontrolled. |
| `onPressedChange` | `(pressed: boolean) => void` | — | Callback fired when the pressed state changes. |
| `disabled` | `boolean` | `false` | Whether the toggle is disabled. |
| `variant` | `"default" \| "outline"` | `"default"` | Visual style variant of the toggle. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the toggle button. |
| `className` | `string` | — | Additional CSS classes for the toggle. |
| `aria-label` | `string` | — | Accessible label for the toggle (required for icon-only). |
#### URL State Props [#url-state-props]
When provided with a `paramName`, the toggle will sync its state with URL parameters via TanStack Router search params.
| Prop | Type | Default | Description |
| --------------------- | ---------------------------- | ------- | ---------------------------------------------------------------------------- |
| `paramName` | `string` | — | URL parameter name for syncing state with URL. Enables URL state management. |
| `paramValue` | `boolean` | — | Controlled value for the URL parameter. |
| `onUrlValueChange` | `(pressed: boolean) => void` | — | Callback when URL parameter value changes. |
| `paramClearOnDefault` | `boolean` | `true` | Remove URL param when value equals default. |
| `paramThrottle` | `number` | — | Throttle URL updates in milliseconds. |
| `paramDebounce` | `number` | — | Debounce URL updates in milliseconds. |
### Notes [#notes]
* **Accessibility**: Always provide `aria-label` for icon-only toggles to ensure screen reader users understand the button's purpose
* **State management**: Use `pressed` and `onPressedChange` for controlled mode, or `defaultPressed` for uncontrolled mode
* **Multiple toggles**: For related toggle buttons, consider using the `ToggleGroup` component which provides better keyboard navigation and state management
* The component uses Base UI primitives with smooth transitions for state changes