## Overview [#overview]
The `ToggleGroup` component manages related toggle buttons. Use the default variant for lightweight ghost-button groups, the outline variant for bordered groups, and the segmented variant for single-selection controls with an animated thumb.
## Usage [#usage]
```tsx
import {
ToggleGroup,
ToggleGroupItem,
} from "@tilt-legal/cubitt-components/toggle-group";
```
```tsx
LeftCenterRight
```
Sync selection with the URL by providing a `paramName`. Single-select groups use a string value, while multi-select groups use a string array.
```tsx
DayWeekMonth
```
`ToggleGroupItem` supports Base UI's `render` prop. Set `nativeButton={false}` when rendering a non-button element such as a link.
```tsx
Day}
value="week"
>
Week
```
## Examples [#examples]
### Segmented [#segmented]
Single-selection segmented groups use the same track, thumb, separator, and hover model as `Tabs`.
```tsx
import {
ToggleGroup,
ToggleGroupItem,
} from "@tilt-legal/cubitt-components/toggle-group";
import {
TextAlignCenter,
TextAlignLeft,
TextAlignRight,
} from "@tilt-legal/cubitt-icons/ui/outline";
export default function Example() {
return (
);
}
```
### Default [#default]
Default groups behave like related ghost toggles and support multiple active items.
```tsx
import {
ToggleGroup,
ToggleGroupItem,
} from "@tilt-legal/cubitt-components/toggle-group";
import {
TextBold,
TextItalic,
TextUnderline,
} from "@tilt-legal/cubitt-icons/ui/outline";
export default function Example() {
return (
);
}
```
### Outline [#outline]
Outline groups add a contextual border around related toggle items.
```tsx
import {
ToggleGroup,
ToggleGroupItem,
} from "@tilt-legal/cubitt-components/toggle-group";
import {
TextBold,
TextItalic,
TextUnderline,
} from "@tilt-legal/cubitt-icons/ui/outline";
export default function Example() {
return (
);
}
```
### Sizes [#sizes]
Segmented groups support text and icon-only layouts at each size.
```tsx
DayWeekMonthYearDayWeekMonthYearDayWeekMonthYear
```
### Separator [#separator]
Use `ToggleGroupSeparator` inside segmented groups to split related options. Separators hide when the active thumb touches them.
```tsx
import {
ToggleGroup,
ToggleGroupItem,
ToggleGroupSeparator,
} from "@tilt-legal/cubitt-components/toggle-group";
export default function Example() {
return (
DayWeekMonthYear
);
}
```
### URL State [#url-state]
Sync toggle group selection with the URL.
```tsx
DayWeekMonthYear
```
### Polymorphic [#polymorphic]
Render items through custom elements while preserving pressed state.
```tsx
import {
ToggleGroup,
ToggleGroupItem,
} from "@tilt-legal/cubitt-components/toggle-group";
export default function Example() {
return (
Day}
value="week"
>
Week
}
value="month"
>
Month
Year
);
}
```
## API Reference [#api-reference]
### ToggleGroup [#togglegroup]
The root container that manages toggle selection.
| Prop | Type | Default | Description |
| --------------- | --------------------------------------- | -------------- | ------------------------------------------------------------------------- |
| `value` | `string \| string[]` | - | Controlled selected value or values. |
| `defaultValue` | `string \| string[]` | - | Initial selected value or values for uncontrolled usage. |
| `onValueChange` | `(value: string \| string[]) => void` | - | Called when selection changes. |
| `multiple` | `boolean` | auto | Enables multiple selection. Segmented groups always use single selection. |
| `groupVariant` | `"default" \| "outline" \| "segmented"` | `"default"` | Visual group style. |
| `variant` | `"default" \| "outline"` | `"default"` | Toggle item variant for non-segmented groups. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Toggle item size. |
| `disabled` | `boolean` | `false` | Disables the whole group. |
| `loop` | `boolean` | `true` | Whether keyboard focus loops. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Group orientation. |
| `className` | `string` | - | Additional classes for layout. |
### URL State Props [#url-state-props]
| Prop | Type | Default | Description |
| --------------------- | --------------------------------------------- | ------- | --------------------------------------------------------- |
| `paramName` | `string` | - | Search parameter name used for URL state. |
| `onUrlValueChange` | `(value: string \| string[] \| 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. |
### ToggleGroupItem [#togglegroupitem]
| Prop | Type | Default | Description |
| -------------- | -------------------------- | --------- | -------------------------------------------------------------- |
| `value` | `string` | - | Required unique item value. |
| `mode` | `"icon"` | - | Square icon-only sizing. Segmented icon items render circular. |
| `disabled` | `boolean` | `false` | Disables one item. |
| `variant` | `"default" \| "outline"` | inherited | Overrides the item variant for non-segmented groups. |
| `size` | `"sm" \| "md" \| "lg"` | inherited | Overrides the item size. |
| `render` | `ReactElement \| function` | - | Renders as a custom element or component. |
| `nativeButton` | `boolean` | `true` | Set to `false` when `render` outputs a non-button element. |
| `className` | `string` | - | Additional item classes. |
| `children` | `React.ReactNode` | - | Item content. |
### ToggleGroupSeparator [#togglegroupseparator]
| Prop | Type | Default | Description |
| ----------- | -------- | ------- | ----------------------------- |
| `className` | `string` | - | Additional separator classes. |
### Notes [#notes]
* Use `multiple` for multi-select default or outline groups.
* Segmented groups force single selection so the animated thumb always has one target.
* Use `aria-label` for icon-only items.
* The segmented variant respects `prefers-reduced-motion`.