/**
* Styles for one item.
* `variant` and `size` use the Toggle classes.
* Pass `null` for an omitted value. The group variant then owns that axis.
*/
export const toggleGroupItemVariants = cva(
`${toggleBaseClass} aria-pressed:z-10`,
{
variants: {
size: toggleSizeClass,
variant: toggleVariantClass,
},
},
)
export type ToggleGroupItemVariantProps = VariantProps<
typeof toggleGroupItemVariants
>
```
#### src/components/ui/toggle-group/toggle-group.astro
```astro
---
import type { HTMLAttributes } from "astro/types"
import { cn } from "cn"
import type { ToggleGroupProps } from "./types.ts"
import { toggleGroupVariants } from "./toggle-group-variants.ts"
/** Div attributes pass through. Give the group an accessible name. */
type Props = HTMLAttributes<"div"> & ToggleGroupProps
const {
class: className,
variant = "default",
size = "default",
orientation = "horizontal",
defaultValue,
multiple,
loop,
disabled,
...props
} = Astro.props
/**
* The controller reads a space-separated list.
* An array and a string with spaces become that list.
*/
const defaultValueAttribute = Array.isArray(defaultValue)
? defaultValue
.flatMap((value) => value.split(/\s+/))
.filter((value) => value.length > 0)
.join(" ")
: defaultValue
---
```
#### src/components/ui/toggle-group/types.ts
```ts
import type { ToggleVariantProps } from '../toggle/toggle-variants.ts'
/**
* Props for a set of toggle buttons that share a selection.
* Div attributes such as `class`, `id`, and `aria-label` pass through.
* Give the group an accessible name with `aria-label` or `aria-labelledby`.
* Place each item directly inside the group. A separator may sit between items.
*/
export interface ToggleGroupProps {
/**
* Visual style for every item that does not set its own `variant`.
* `outline` joins the items into one control. The default style leaves a small gap.
*
* @default "default"
*/
variant?: ToggleVariantProps['variant']
/**
* Height and padding for every item that does not set its own `size`.
*
* @default "default"
*/
size?: ToggleVariantProps['size']
/**
* Direction of the items and of the arrow keys.
*
* @default "horizontal"
*/
orientation?: 'horizontal' | 'vertical'
/**
* Value selected at first render.
* Pass one value, a space-separated list, or an array.
* A value matches an item `value`. Use a value with no spaces.
* In single selection, the first known value is selected.
*/
defaultValue?: string | string[]
/**
* Allow more than one pressed item.
*
* @default false
*/
multiple?: boolean
/**
* Move focus from the last item to the first item, and the reverse.
*
* @default true
*/
loop?: boolean
/**
* Block changes to every item.
*
* @default false
*/
disabled?: boolean
}
/**
* Props for one toggle in the group.
* Button attributes such as `class` and `aria-label` pass through.
* The control is its own button. It uses the Toggle styles.
*/
export interface ToggleGroupItemProps {
/**
* Value stored for this item.
* The group matches this value against `defaultValue`.
* Use a value with no spaces.
*/
value: string
/**
* Visual style for this item.
* When omitted, the item uses the group's `variant`.
*/
variant?: ToggleVariantProps['variant']
/**
* Control size for this item.
* When omitted, the item uses the group's `size`.
*/
size?: ToggleVariantProps['size']
/**
* Block changes to this item.
*
* @default false
*/
disabled?: boolean
}
/**
* Props for a divider between toggle group items.
* Separator attributes such as `class` pass through.
*/
export interface ToggleGroupSeparatorProps {
/**
* Direction of the divider line.
* Use `vertical` between items in a horizontal group.
* Use `horizontal` between items in a vertical group.
*
* @default "vertical"
*/
orientation?: 'horizontal' | 'vertical'
}
```
Optional preset: inspect a stylesheet at /presets/{style}.css, save it to src/styles/presets/{style}.css, and import it after the global stylesheet. Set data-preset="{style}" on your layout or a component container. See [Theming](/docs/theming) for details.
## Usage
```astro
---
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
---
```
```astro index.astro wrap lineNumbers
Left
Center
Right
```
Set `multiple` when more than one item can stay pressed. Pass several values as an array or as a space-separated string.
```astro index.astro wrap lineNumbers
Bold
Italic
Underline
```
`variant` and `size` on the group apply to each item that does not set its own value. `outline` joins the items. The default variant leaves a small gap. Each item uses the [Toggle](/components/toggle) styles.
## Composition
Place the parts directly inside `ToggleGroup`:
```text
ToggleGroup
├── ToggleGroupItem
├── ToggleGroupSeparator
└── ToggleGroupItem
```
`ToggleGroupSeparator` is optional. Use `orientation="horizontal"` on the separator when the group is vertical.
## Examples
### Several selections
```astro
---
import BoldIcon from "@lucide/astro/icons/bold"
import ItalicIcon from "@lucide/astro/icons/italic"
import UnderlineIcon from "@lucide/astro/icons/underline"
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
---
```
### Disabled
`disabled` on the group blocks every item. `disabled` on one item blocks that item.
```astro
---
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
---
Left
Center
Right
Left
Center
Right
```
### Sizes
```astro
---
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
---
{(["sm", "default", "lg"] as const).map((size) => (
Left
Center
Right
))}
```
### Vertical
```astro
---
import {
ToggleGroup,
ToggleGroupItem,
ToggleGroupSeparator,
} from "@/components/ui/toggle-group"
---
Start
Center
End
```
## API Reference
### ToggleGroup
Div attributes such as `class`, `id`, and `aria-label` pass through.
### ToggleGroupItem
Button attributes such as `class` and `aria-label` pass through. Give an icon-only item an accessible name.
### ToggleGroupSeparator
Separator attributes such as `class` pass through.
Read the [installed source](/r/toggle-group.json) for the component source.
See the [data-slot docs](https://data-slot.com/components/toggle-group/) for the controller, events, and keyboard model.
## When to use Toggle Group
Use Toggle Group when the visitor keeps one option pressed, or several options pressed, and every option stays visible. Put the group label in `aria-label` when nearby text does not name the group. Use one item value with no spaces.
A change event on the group carries the selected values. Listen for `toggle-group:change` on the group element. `event.detail.value` is an array of strings.
## Keyboard and behavior
Tab moves to the active item. Arrow keys move focus along `orientation`. Home moves to the first item. End moves to the last item. Enter and Space press the focused item. Set `loop={false}` to stop focus at the ends.
One item stays pressed at a time unless `multiple` is set. Press the active item again to clear it. A disabled group and a disabled item ignore pointer and keyboard changes.
## Theme and layout
Pressed, hover, focus, and disabled styles use the Toggle variants and the current theme. Check an icon-only item with an accessible name. In an outline group, keep item sizes equal so the shared border stays even. Color should reinforce the pressed state, not be its only indication.