Skip to content
WunderUI

Checkbox Button Group

Free

Let people turn any number of short options on or off, shown as a row of toggle buttons.

npx wunderui-cli add checkbox-button-group

Playground

Installation

bash
npx wunderui-cli add checkbox-button-group

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

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

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.

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 for

  • Radio Button Group for exactly one choice from a few short options, where arrow keys choose and the choice cannot be cleared
  • Checkbox for a long list, or options that need a label and a description
  • Toggle for a single button that is on or off
  • Segment for switching between views, with one always selected

Content

A button holds a word or two. A text label gets a checkbox square in front, so the choice never relies on colour alone, and an icon-only button needs an aria-label.

Layout

The row wraps by itself in a narrow container. For a stack, set the orientation to vertical so the arrow keys follow the layout.

States

Disable the whole group, or one option that is not available. Hover, pressed and focus are real states, so move the pointer over a button or press Tab.

Error and invalid

The error belongs to the group. Every button that is off turns red together, one message says what to do, and turning an option on clears it.

Choose at least one channel.

Keyboard interactions

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.

TaborShiftTab
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.
ArrowRightorArrowLeft
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.
ArrowDownorArrowUp
Does the same in a group with . In a horizontal group these keys do nothing.
HomeorEnd
Moves focus to the first or the last button.
SpaceorEnter
Turns the focused button on or off and calls . Several buttons can stay on.

Behavior and motion

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

The parts the component is made of. Each one renders a you can target from CSS.

  • data-slot="checkbox-button-group"

    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.

  • 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.

  • data-slot="toggle-button-mark"Optional

    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.

  • Optional

    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

  • 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.

  • Do

    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.

  • Do

    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.

  • Do

    Give every icon-only ToggleButton an aria-label such as Bold. The pressed state is announced, but the icon alone has no name.

  • Do

    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

    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

    Don't use it to switch between views or pages. People expect a Segment or Tabs for that.

API reference

CheckboxButtonGroup is a div with the group role and takes the props below plus every native attribute. The buttons inside are ToggleButton, described on the Toggle page.

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.

PropTypeDefaultDescription
valuereadonly Value[]—The values of the buttons that are on, as an array. Pass it with to control the group; use to let the group keep it.
defaultValuereadonly 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.
onValueChange(groupValue, eventDetails) => void—Called when a button is turned on or off, with the new array of values.
disabledbooleanfalseEvery button ignores clicks and keys and is dimmed to 40 %. Disable a single option on its ToggleButton instead.
orientation"horizontal" | "vertical""horizontal"The direction the arrow keys move in. uses Left and Right, uses Up and Down. It does not change the layout: add classes for a column.
loopFocusbooleantrueWhether the arrow keys wrap from the last button to the first and back. Set it to to stop at the ends.
multiplebooleanfalseNo effectThe group sets it to so any number of buttons can be on. Leave it alone: use RadioButtonGroup for a single choice.
renderReactElement | (props, state) => ReactElement—Replaces the element of the group with another tag or component. Accepts an element or a function that returns one.
classNamestring | (state) => string | undefined—Extra classes, merged with the group's own . Use it for the layout: makes a column.
styleCSSProperties | (state) => CSSProperties | undefined—Inline style for the group, an object or a function of the state.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("checkbox-button-group")
Installnpx wunderui-cli add checkbox-button-group

The full library index for assistants is at /llms.txt.