# Toggle Group

> Chips that filter or switch a view; one or several can be on.

A toggle group is a row of chips that filter the content on the page, such as release statuses, or switch how it shows.

## When to use

- Use it for quick filters above a list, with the count in each chip: "Terbit 12".
- A status filter **always has one value**: "Semua" by default, and clicking the active chip keeps it on.
- Use [Tabs](https://design.sosialoka.tech/components/tabs/) when each option shows different content, and a [Select](https://design.sosialoka.tech/components/select/) for more than five options.
- Use several-on mode for filters that combine, such as genres.

_Live preview of the React and Vue versions: https://design.sosialoka.tech/components/toggle-group/_

## Anatomy

1. Selected chip
2. Chip
3. Group, one value at a time

Chips `h-8` on `radius-md` with a `border`, 8px apart, never pill-shaped. An active chip is `primary-soft` with `primary-text` and a `primary`-tinted border. An optional count sits after the label in `muted-foreground`.

## Variants

| Mode | Use it for |
| --- | --- |
| One on | Status filters, view switches. |
| Several on (`multiple`) | Filters that combine. |

The single **Toggle** (one button that stays pressed) installs with the group and has no page of its own.

## Props

| React | Vue | Flutter | Type | Default | Use |
| --- | --- | --- | --- | --- | --- |
| `multiple` | `type="single"` / `"multiple"` | `ShadToggleGroup` / `ShadToggleGroup.multiple` | mode | one on | How many chips can be on. |
| `value` (array) / `onValueChange` | `v-model` | `initialValue` / `onChanged` | value | none | The chips that are on. |
| keep one on: ignore an empty value | keep one on: ignore an empty value | `allowDeselection: false` | boolean | can be emptied | Keeps a status filter from going empty. |
| `variant="outline"` | `variant="outline"` | `ShadToggleVariant.outline` | text | `default` | The chip look. |
| `spacing` | `spacing` | `spacing` | number | `2` (React), `0` (Vue) | The gap between chips; `0` joins them. Use `2`. |

## Code

**React**
```tsx
import { useState } from "react"
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"

const statuses = [
  { value: "all", label: "Semua", count: 24 },
  { value: "published", label: "Terbit", count: 12 },
  { value: "pending", label: "Menunggu", count: 8 },
  { value: "rejected", label: "Ditolak", count: 4 },
]

export default function ToggleGroupDemo() {
  const [status, setStatus] = useState("all")
  return (
    <ToggleGroup
      variant="outline"
      spacing={2}
      aria-label="Filter status"
      value={[status]}
      // A status filter always has one value: clicking the active chip keeps it on.
      onValueChange={(value) => value.length > 0 && setStatus(value[value.length - 1])}
    >
      {statuses.map((s) => (
        <ToggleGroupItem key={s.value} value={s.value}>
          {s.label}
          <span className="tabular-nums text-muted-foreground">{s.count}</span>
        </ToggleGroupItem>
      ))}
    </ToggleGroup>
  )
}
```

**Vue**
```vue
<script setup lang="ts">
import { ref } from "vue"
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"

const statuses = [
  { value: "all", label: "Semua", count: 24 },
  { value: "published", label: "Terbit", count: 12 },
  { value: "pending", label: "Menunggu", count: 8 },
  { value: "rejected", label: "Ditolak", count: 4 },
]
const status = ref("all")

// A status filter always has one value: clicking the active chip keeps it on.
function pick(value: unknown) {
  if (typeof value === "string" && value) status.value = value
}
</script>

<template>
  <ToggleGroup type="single" variant="outline" :spacing="2" aria-label="Filter status" :model-value="status" @update:model-value="pick">
    <ToggleGroupItem v-for="s in statuses" :key="s.value" :value="s.value">
      {{ s.label }}
      <span class="tabular-nums text-muted-foreground">{{ s.count }}</span>
    </ToggleGroupItem>
  </ToggleGroup>
</template>
```

**Flutter**
```dart
import 'package:flutter/widgets.dart';
import 'package:shadcn_ui/shadcn_ui.dart';

const releaseStatuses = [('all', 'Semua', 24), ('published', 'Terbit', 12), ('pending', 'Menunggu', 8), ('rejected', 'Ditolak', 4)];

class ToggleGroupDemo extends StatelessWidget {
  const ToggleGroupDemo({super.key});

  @override
  Widget build(BuildContext context) {
    final theme = ShadTheme.of(context);
    // A status filter always has one value: allowDeselection keeps the active chip on.
    return ShadToggleGroup<String>(
      initialValue: 'all',
      allowDeselection: false,
      variant: ShadToggleVariant.outline,
      spacing: 8,
      items: [
        for (final (value, label, count) in releaseStatuses)
          ShadToggleGroupItem(
            value: value,
            child: Row(
              mainAxisSize: MainAxisSize.min,
              spacing: 6,
              children: [Text(label), Text('$count', style: theme.textTheme.muted)],
            ),
          ),
      ],
    );
  }
}
```

## Install

**React**
```bash
npx shadcn@latest add https://design.sosialoka.tech/r/react/toggle-group.json
```

**Vue**
```bash
npx shadcn-vue@latest add https://design.sosialoka.tech/r/vue/toggle-group.json
```

## Accessibility

- Name the group with `aria-label`, such as "Filter status".
- Each chip says whether it is on with `aria-pressed`.
- Arrow keys move between chips; Space and Enter turn one on.
- Put the count inside the chip, so it is read with the label.
