Checkbox Button Group
FreeLet people turn any number of short options on or off, shown as a row of toggle buttons.
npx wunderui-cli add checkbox-button-groupPlayground
Installation
npx wunderui-cli add checkbox-button-groupWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { CheckboxButtonGroup } from "@/components/ui/toggle-button-group"Then use it:
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.
Choose at least two channels.
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.
- TaborShift+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.
- 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.
- 1data-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.
- 2
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.
- 3data-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.
- 4Optional
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| value | readonly 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. |
| 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. |
| onValueChange | (groupValue, eventDetails) => void | — | Called when a button is turned on or off, with the new array of values. |
| disabled | boolean | false | Every 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. |
| loopFocus | boolean | true | Whether the arrow keys wrap from the last button to the first and back. Set it to to stop at the ends. |
| multiple | boolean | false | No effectThe group sets it to so any number of buttons can be on. Leave it alone: use RadioButtonGroup for a single choice. |
| render | ReactElement | (props, state) => ReactElement | — | Replaces the element of the group with another tag or component. Accepts an element or a function that returns one. |
| className | string | (state) => string | undefined | — | Extra classes, merged with the group's own . Use it for the layout: makes a column. |
| style | CSSProperties | (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.
get_component("checkbox-button-group")npx wunderui-cli add checkbox-button-groupThe full library index for assistants is at /llms.txt.