Checkbox Group

Checkboxes under one label, hint, error and requirement. Free, MIT · Forms and input › Checkboxes and sliders

Native checkboxes in a named group with one label, description, error and "at least one" requirement, as React Aria's CheckboxGroup. Inside a FormField the field's label, description and error describe the group instead.

Installation

npx valyro-cli@latest add checkbox-group

npx shadcn@latest add https://valyro.xyz/r/checkbox-group.json

npm install valyro-ui

import 'valyro-ui/styles.css';
import { CheckboxGroup } from 'valyro-ui';

Props

Prop	Type	Default
`options`	`CheckboxGroupOption[]`		Checkboxes in order, each with a label and an optional description. Or compose them as children: `CheckboxGroup.Item`.
`children`	`ReactNode`		The compound form instead of `options`: `CheckboxGroup.Item` elements.
`value`	`string[]`		Checked values, in the order they were checked.
`defaultValue`	`string[]`		Initial `value` when uncontrolled.
`onValueChange`	`(value: string[]) => void`		Called with the new `value` when it changes.
`name`	`string`		Name of the checkboxes: each checked one submits its value under it.
`label`	`ReactNode`		Visible name above the checkboxes, linked to the group. Outside a FormField a group needs a name (this, or an `aria-label` / `aria-labelledby`), or a screen reader reads the checkboxes with no question.
`description`	`ReactNode`		Helper text under the checkboxes, read with the group. Hidden while `error` is set.
`error`	`ReactNode`		Error message; any truthy value marks the group invalid and replaces the description.
`required`	`boolean`		At least one box must be checked: a required mark, the `labels.required` word, and the form does not submit without one.
`invalid`	`boolean`	`false`	Error colour and `aria-invalid` on every checkbox (set by `error` or a FormField too).
`disabled`	`boolean`	`false`	Disables every checkbox.
`readOnly`	`boolean`	`false`	The checks show but cannot change.
`orientation`	`'vertical' \| 'horizontal'`	`'vertical'`	Stack the checkboxes in a column or lay them out in a row.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Checkbox and text size.
`labels`	`Partial<CheckboxGroupLabels>`		Overrides for the built-in English text; keys left out keep their defaults.

Compound parts

CheckboxGroup.Item (CheckboxGroupItem)

Related components

Checkbox — Checkboxes
Radio Group — Pick exactly one option
Switch — On/off toggle
Slider — Range slider
Histogram Range — Price range with a histogram, two thumbs and inputs
Rating Input — Star rating
Text Input — Text fields
Textarea — Multiline text input
Search Input — Search field
Mentions Input — Text with @mentions and #tags, async suggestions
Tags Input — Tag entry
Select — Pick one option from a list

Previous: Checkbox · Next: Radio Group · All Forms and input