# Checkbox Button Group

A multi-select group of toggle-styled buttons.

- Category: Forms
- Page: https://wunderui.com/components/checkbox-button-group
- Tier: Free

## Install

```bash
npx wunderui-cli add checkbox-button-group
```

## Import

```tsx
import { CheckboxButtonGroup } from "@/components/ui/toggle-button-group"
```

## Minimal usage

Then use it:

```tsx
import { CheckboxButtonGroup } from "@/components/ui/checkbox-button-group"
import { ToggleButton } from "@/components/ui/toggle"

export function Channels() {
  return (
    <CheckboxButtonGroup defaultValue={["email"]} aria-label="Notify me by">
      <ToggleButton value="email">Email</ToggleButton>
      <ToggleButton value="push">Push</ToggleButton>
      <ToggleButton value="sms">SMS</ToggleButton>
    </CheckboxButtonGroup>
  )
}
```

Expected result: You see three buttons, Email on with a check and Push and SMS off. A click or Space turns a button on or off, and arrow keys move focus between them.

## Usage

```tsx
import { CheckboxButtonGroup } from "@/components/ui/checkbox-button-group"
import { ToggleButton } from "@/components/ui/toggle"

export function Example() {
  return (
    <CheckboxButtonGroup defaultValue={["email"]} aria-label="Notify me by">
      <ToggleButton value="email">Email</ToggleButton>
      <ToggleButton value="push">Push</ToggleButton>
      <ToggleButton value="sms">SMS</ToggleButton>
    </CheckboxButtonGroup>
  )
}
```

## When to use

### Use Checkbox Button Group for

- A few short options that can be combined, such as notification channels or days of the week
- Text styles and filters, where each option is a word or an icon
- A choice that should stay visible and one click away instead of hiding in a menu

### Use something else

- [Radio Button Group](https://wunderui.com/components/radio-button-group) for exactly one choice from a few short options, where arrow keys choose and the choice cannot be cleared
- [Checkbox](https://wunderui.com/components/checkbox) for a long list, or options that need a label and a description
- [Toggle](https://wunderui.com/components/toggle) for a single button that is on or off
- [Segment](https://wunderui.com/components/segment) for switching between views, with one always selected

## Keyboard

The group is one tab stop: arrow keys move focus inside it and Tab moves out. Only Space and Enter change a button, unlike RadioButtonGroup, where arrow keys also choose.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus into the group, to the first button at first and to the button that had focus last after that, and out of it again. The other buttons are not tab stops. |
| `ArrowRight` or `ArrowLeft` | Moves focus to the next or previous button without changing it. From the last button it wraps to the first. In a vertical group these keys do nothing. |
| `ArrowDown` or `ArrowUp` | Does the same in a group with `orientation="vertical"`. In a horizontal group these keys do nothing. |
| `Home` or `End` | Moves focus to the first or the last button. |
| `Space` or `Enter` | Turns the focused button on or off and calls `onValueChange`. Several buttons can stay on. |

## Behavior

What the group does itself, and what it leaves to the page.

- **Any number on:** Pressing a button adds its value to the array, and pressing it again removes it. The array can be empty, so a rule such as at least one is yours to enforce.
- **Controlled or not:** Pass the value and a change handler to own the buttons that are on, or a default value to let the group keep them. Each button is matched by its value.
- **Toggles, not radios:** Each option is a button that reports a pressed state, inside a group. Any number can be on and none is valid, and the square is drawn, not an input, so the group sends no form value by itself.
- **Names:** The group needs a name from an aria-label or aria-labelledby. A button is named by its text, an icon-only button needs its own aria-label, and the mark is hidden from assistive technology.
- **Wrapping:** The row wraps by itself when the container is narrow, with an 8 px gap in both directions. For a column, set the vertical orientation together with column layout classes.
- **Invalid:** Marking the group invalid turns every button that is off red together. Buttons that are on and disabled buttons keep their own look, and the message is yours to write under the group.
- **Disabled:** Disabling the group dims every button to 40 % and skips it with Tab and arrow keys. On one button it dims only that button.
- **Motion:** Border, fill and the check change quickly. Nothing moves, so the group has no layout animation.
- **Reduced motion:** With reduced motion the colour and opacity changes still run as fades. Nothing in the group moves, so nothing else changes.

## Anatomy

- `CheckboxButtonGroup`: A wrapping row of toggle buttons where any number can be on, with an 8 px gap. The value is the list of buttons that are on, and the group needs an aria-label.
- `ToggleButton`: One button, on or off, with its own value. It shows the pressed state in the indigo tint, and an icon-only button needs an aria-label.
- `Mark`: The 16 px checkbox square before the label, with a check while the button is on. It is drawn for buttons with a text label and left out for icon-only ones, and you can hide it.
- `Icon`: An optional Lucide icon before the label, 16 px with a 1.5 stroke. It takes the text colour of the button, so it turns indigo with the label.

## Best practices

### When to use

- Use CheckboxButtonGroup for a few short options that can be combined, like text styles or filters. For one choice use RadioButtonGroup, and for long options use Checkbox or Selector Item.

### Do

- Pick the group by what the options mean. CheckboxButtonGroup is a set of toggles where any number can be on, while RadioButtonGroup is one choice that arrow keys select and cannot be cleared.
- Keep the value as an array of strings and update it in the change handler. Wrapping on narrow screens is built in, so no custom breakpoints are needed.
- Name the group with a visible label and aria-labelledby, or with an aria-label. A screen reader announces the name when focus enters the group.
- Give every icon-only ToggleButton an aria-label such as Bold. The pressed state is announced, but the icon alone has no name.
- Put the error on the group: mark it invalid and write one message under it. Do not repeat the message on every button.

### Don't

- Don't use it for options with a sentence of explanation. A button holds a word or two, so use a Checkbox or Selector Item with a description.
- Don't set the vertical orientation without stacking the buttons, or arrow keys will move in a direction the layout does not show.
- Don't use it to switch between views or pages. People expect a Segment or Tabs for that.

## API reference

### CheckboxButtonGroup

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes, merged with the group's own `flex flex-wrap gap-2`. Use it for the layout: `flex-col items-stretch` makes a column. |
| defaultValue | readonly Value[] |  | The values of the buttons that are on at the start, when the group keeps its own state. Leave it out to start with every button off. |
| disabled | boolean | false | Every button ignores clicks and keys and is dimmed to 40 %. Disable a single option on its ToggleButton instead. |
| loopFocus | boolean | true | Whether the arrow keys wrap from the last button to the first and back. Set it to `false` to stop at the ends. |
| multiple | boolean | false | The group sets it to `true` so any number of buttons can be on. Leave it alone: use RadioButtonGroup for a single choice. No effect in this version. |
| onValueChange | ((groupValue: Value[], eventDetails: ToggleGroup.ChangeEventDetails) => void) |  | Called when a button is turned on or off, with the new array of values. |
| orientation | "horizontal" \| "vertical" | 'horizontal' | The direction the arrow keys move in. `horizontal` uses Left and Right, `vertical` uses Up and Down. It does not change the layout: add `flex-col` classes for a column. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the element of the group with another tag or component. Accepts an element or a function that returns one. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline style for the group, an object or a function of the state. |
| value | readonly Value[] |  | The values of the buttons that are on, as an array. Pass it with `onValueChange` to control the group; use `defaultValue` to let the group keep it. |

Also accepts React.HTMLAttributes attributes.

## Examples

### Content: label, icon only and icon with label

```tsx
import { CheckboxButtonGroup } from "@/components/ui/checkbox-button-group"
import { ToggleButton } from "@/components/ui/toggle"

export function Example() {
  return (
    <CheckboxButtonGroup defaultValue={["email"]} aria-label="Notify me by">
      <ToggleButton value="email">Email</ToggleButton>
      <ToggleButton value="push">Push</ToggleButton>
      <ToggleButton value="sms">SMS</ToggleButton>
    </CheckboxButtonGroup>
  )
}
```

### Layout: row, wrapping and column

```tsx
import { CheckboxButtonGroup } from "@/components/ui/checkbox-button-group"
import { ToggleButton } from "@/components/ui/toggle"

export function Example() {
  return (
    <CheckboxButtonGroup defaultValue={["email"]} aria-label="Notify me by">
      <ToggleButton value="email">Email</ToggleButton>
      <ToggleButton value="push">Push</ToggleButton>
      <ToggleButton value="sms">SMS</ToggleButton>
    </CheckboxButtonGroup>
  )
}
```

### States: default, disabled group and disabled option

```tsx
import { CheckboxButtonGroup } from "@/components/ui/checkbox-button-group"
import { ToggleButton } from "@/components/ui/toggle"

export function Example() {
  return (
    <CheckboxButtonGroup aria-label="Notify me by">
      <ToggleButton value="email">Email</ToggleButton>
      <ToggleButton value="push">Push</ToggleButton>
      <ToggleButton value="sms">SMS</ToggleButton>
    </CheckboxButtonGroup>
  )
}
```

### Error and invalid: the group, not the button

```tsx
import { useState } from "react"
import { CheckboxButtonGroup } from "@/components/ui/checkbox-button-group"
import { ToggleButton } from "@/components/ui/toggle"

export function Example() {
  const [value, setValue] = useState<string[]>([])
  const invalid = value.length < 1

  return (
    <div className="flex flex-col gap-2">
      <CheckboxButtonGroup
        value={value}
        onValueChange={setValue}
        aria-label="Notify me by"
        aria-invalid={invalid}
        aria-describedby={invalid ? "channels-error" : undefined}
      >
        <ToggleButton value="email">Email</ToggleButton>
        <ToggleButton value="push">Push</ToggleButton>
        <ToggleButton value="sms">SMS</ToggleButton>
      </CheckboxButtonGroup>
      {invalid && (
        <p id="channels-error" className="text-sm text-text-error">
          Choose at least one channel.
        </p>
      )}
    </div>
  )
}
```

## In context

### Notifications: a group with a group error

At least one channel is needed. After a first save attempt with none on, the buttons that are off turn red and one message appears under the group.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { CheckboxButtonGroup } from "@/components/ui/checkbox-button-group"
import { ToggleButton } from "@/components/ui/toggle"

export function Example() {
  const [value, setValue] = useState<string[]>([])
  const [tried, setTried] = useState(false)
  const [saved, setSaved] = useState(false)
  const invalid = tried && value.length === 0

  return (
    <div className="flex flex-col gap-4">
      <div className="flex flex-col gap-3">
        <div className="flex flex-col gap-1">
          <p id="channels-label" className="text-sm font-medium text-foreground">
            Notify me by
          </p>
          <p id="channels-hint" className="text-sm text-text-secondary">
            Choose where mentions and comments reach you.
          </p>
        </div>
        <CheckboxButtonGroup
          value={value}
          onValueChange={(next) => {
            setValue(next)
            setSaved(false)
          }}
          aria-labelledby="channels-label"
          aria-describedby={invalid ? "channels-error" : "channels-hint"}
          aria-invalid={invalid}
        >
          <ToggleButton value="email">Email</ToggleButton>
          <ToggleButton value="push">Push</ToggleButton>
          <ToggleButton value="sms">SMS</ToggleButton>
        </CheckboxButtonGroup>
        {invalid && (
          <p id="channels-error" className="text-sm text-text-error">
            Choose at least one channel.
          </p>
        )}
      </div>
      <Button
        variant="gradient"
        onClick={() => {
          setTried(true)
          setSaved(value.length > 0)
        }}
      >
        Save
      </Button>
      <p aria-live="polite" className="min-h-5 text-sm text-text-secondary">
        {saved ? `Saved: ${value.join(", ")}.` : ""}
      </p>
    </div>
  )
}
```

### Text style: icon-only buttons that apply at once

Four styles can be on together. Each icon has an aria-label, and the text under the group follows every press without a button.

```tsx
import { useState } from "react"
import { Bold, Italic, Strikethrough, Underline } from "lucide-react"
import { CheckboxButtonGroup } from "@/components/ui/checkbox-button-group"
import { ToggleButton } from "@/components/ui/toggle"

export function Example() {
  const [value, setValue] = useState<string[]>(["bold"])
  const on = (style: string) => value.includes(style)

  return (
    <div className="flex flex-col gap-3">
      <CheckboxButtonGroup value={value} onValueChange={setValue} aria-label="Text style">
        <ToggleButton value="bold" aria-label="Bold">
          <Bold className="size-4" />
        </ToggleButton>
        <ToggleButton value="italic" aria-label="Italic">
          <Italic className="size-4" />
        </ToggleButton>
        <ToggleButton value="underline" aria-label="Underline">
          <Underline className="size-4" />
        </ToggleButton>
        <ToggleButton value="strike" aria-label="Strikethrough">
          <Strikethrough className="size-4" />
        </ToggleButton>
      </CheckboxButtonGroup>
      <p
        className={[
          "rounded-xl border border-border bg-card p-4 text-sm text-foreground",
          on("bold") ? "font-semibold" : "",
          on("italic") ? "italic" : "",
          on("underline") ? "underline" : "",
          on("strike") ? "line-through" : "",
        ].join(" ")}
      >
        Version 0.4 adds a sliding Segment pill and concentric radii.
      </p>
    </div>
  )
}
```

### Repeat on: weekday buttons with a summary

Seven short options in one row, wrapping on a narrow screen. A line under the group says in words what the buttons mean.

```tsx
import { useState } from "react"
import { CheckboxButtonGroup } from "@/components/ui/checkbox-button-group"
import { ToggleButton } from "@/components/ui/toggle"

const DAYS = [
  { value: "mon", label: "Mon", name: "Monday" },
  { value: "tue", label: "Tue", name: "Tuesday" },
  { value: "wed", label: "Wed", name: "Wednesday" },
  { value: "thu", label: "Thu", name: "Thursday" },
  { value: "fri", label: "Fri", name: "Friday" },
  { value: "sat", label: "Sat", name: "Saturday" },
  { value: "sun", label: "Sun", name: "Sunday" },
]

export function Example() {
  const [value, setValue] = useState<string[]>(["mon", "wed", "fri"])
  const names = DAYS.filter((day) => value.includes(day.value)).map((day) => day.name)

  return (
    <div className="flex flex-col gap-3">
      <p id="repeat-label" className="text-sm font-medium text-foreground">
        Repeat on
      </p>
      <CheckboxButtonGroup value={value} onValueChange={setValue} aria-labelledby="repeat-label">
        {DAYS.map((day) => (
          <ToggleButton key={day.value} value={day.value}>
            {day.label}
          </ToggleButton>
        ))}
      </CheckboxButtonGroup>
      <p aria-live="polite" className="text-sm text-text-secondary">
        {names.length ? `Repeats every ${names.join(", ")}.` : "Does not repeat."}
      </p>
    </div>
  )
}
```

## For AI agents

`get_component("checkbox-button-group")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
