Checkbox Group
A CheckboxGroup allows users to select one or more items from a list of choices.
Installation
npx nextui-cli@latest add checkbox
The above command is for individual installation only. You may skip this step if @nextui-org/react is already installed globally.
Import
NextUI exports 2 checkbox-related components:
- CheckboxGroup: The root component, it wraps the label and the wrapper.
- Checkbox: The checkbox component.
Usage
Disabled
Horizontal
Controlled
You can use the value and onValueChange properties to control the checkbox input value.
Invalid
Slots
- base: Checkbox group root wrapper, it wraps the label and the wrapper.
- wrapper: Checkbox group wrapper, it wraps all checkboxes.
- label: Checkbox group label, it is placed before the wrapper.
- description: The description of the checkbox group.
- errorMessage: The error message of the checkbox group.
Custom Styles
You can customize the CheckboxGroup component by passing custom Tailwind CSS classes to the component slots.
Custom Implementation
In case you need to customize the checkbox even further, you can use the useCheckboxGroup hook to create your own implementation.
Note: We used Tailwind Variants to implement the styles above, you can use any other library such as clsx to achieve the same result.
API
Checkbox Group Props
| Attribute | Type | Description | Default |
|---|---|---|---|
| children | ReactNode[] | ReactNode[] | The checkboxes items. | - |
| orientation | vertical | horizontal | The axis the checkbox group items should align with. | vertical |
| color | default | primary | secondary | success | warning | danger | The color of the checkboxes. | primary |
| size | xs | sm | md | lg | xl | The size of the checkboxes. | md |
| radius | none | base | xs | sm | md | lg | xl | full | The radius of the checkboxes. | md |
| name | string | The name of the CheckboxGroup, used when submitting an HTML form. | - |
| label | string | The label of the CheckboxGroup. | - |
| value | string[] | The current selected values. (controlled). | - |
| lineThrough | boolean | Whether the checkboxes label should be crossed out. | false |
| defaultValue | string[] | The default selected values. (uncontrolled). | - |
| isInvalid | boolean | Whether the checkbox group is invalid. | false |
| validationState | valid | invalid | Whether the inputs should display its "valid" or "invalid" visual styling. (Deprecated) use isInvalid instead. | - |
| description | ReactNode | The checkbox group description. | - |
| errorMessage | ReactNode | ((v: ValidationResult) => ReactNode) | The checkbox group error message. | - |
| validate | (value: string[]) => ValidationError ｜ true ｜ null ｜ undefined | Validate input values when committing (e.g. on blur), returning error messages for invalid values. Validation errors are displayed upon form submission if validationBehavior is set to native. For real-time validation, use the isInvalid prop. | - |
| validationBehavior | native | aria | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. | aria |
| isDisabled | boolean | Whether the checkbox group is disabled. | false |
| isRequired | boolean | Whether user checkboxes are required on the input before form submission. | false |
| isReadOnly | boolean | Whether the checkboxes can be selected but not changed by the user. | - |
| disableAnimation | boolean | Whether the animation should be disabled. | false |
| classNames | Record<"base"｜ "wrapper"｜ "label", string> | Allows to set custom class names for the checkbox group slots. | - |
Checkbox Group Events
| Attribute | Type | Description |
|---|---|---|
| onChange | (value: string[]) => void | Handler that is called when the value changes. |
