---
title: "ToggleGroup"
description: "A set of options that stay pressed, such as view or density. It supports single or multiple selection and keeps focus inside the group."
kind: component
id: C-041
registry: "toggle-group"
docs: "https://koten.codehive.com.co/components/toggle-group"
markdown: "https://koten.codehive.com.co/md/components/toggle-group.md"
install: "npx shadcn@latest add https://koten.codehive.com.co/r/toggle-group.json"
language: en
---

# ToggleGroup · 切替

> Component C-041 in the Koten UI catalog.

A set of options that stay pressed, such as view or density. It supports single or multiple selection and keeps focus inside the group.

> Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031).

## Install

Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project.

```bash
# Node
npx shadcn@latest add https://koten.codehive.com.co/r/toggle-group.json

# Bun
bunx shadcn@latest add https://koten.codehive.com.co/r/toggle-group.json
```

## Files

- `@/components/ui/toggle-group.tsx`
- `@/lib/koten/cn.ts`
- `@/lib/koten/format.ts`
- `@/lib/koten/intl.ts`
- `@/lib/koten/labels.ts`
- `@/lib/koten/provider.tsx`

## Reference

- Upstream primitive: https://base-ui.com/react/components/toggle-group

## Examples

### Single selection

Grid or list view; only one option stays pressed.

```tsx
<ToggleGroup
  label="Order view"
  value={value}
  onValueChange={setValue}
  items={[
    { value: "grid", label: "Grid", icon: <Grid2X2 className="size-3.5" /> },
    { value: "list", label: "List", icon: <List className="size-3.5" /> },
  ]}
/>
```

### Multiple selection

With multiple, several density options can stay pressed.

```tsx
<ToggleGroup
  label="Table density"
  multiple
  value={value}
  onValueChange={setValue}
  items={[
    { value: "compact", label: "Compact" },
    { value: "default", label: "Default" },
    { value: "comfortable", label: "Comfortable" },
  ]}
/>
```

## Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `label` | `string` | `—` | Accessible name of the group. |
| `items` | `ToggleGroupItem[]` | `—` | Each item defines value, label, icon and an optional disabled. |
| `value` | `readonly string[]` | `—` | Pressed values in controlled mode. |
| `defaultValue` | `readonly string[]` | `—` | Initial values in uncontrolled mode. |
| `onValueChange` | `(value: string[]) => void` | `—` | Returns the full array of pressed values. |
| `multiple` | `boolean` | `false` | Allows more than one option to stay pressed. |
| `disabled` | `boolean` | `false` | Disables every option in the group. |
| `orientation` | `horizontal \| vertical` | `horizontal` | Aligns the group and defines the arrow-key axis. |
| `className` | `string` | `—` | Applied to the group container. |

## Accessibility

- label names the whole group through aria-label.
- Each option exposes aria-pressed; Base UI moves focus with the arrow keys.
- Options with an icon keep their name in sr-only text.
- The pressed state changes background, weight and text color, not color alone.

## Sources

- Catalog page: https://koten.codehive.com.co/components/toggle-group
- Markdown: https://koten.codehive.com.co/md/components/toggle-group.md
- Repository: https://github.com/codehive-colombia/koten