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

AttributeTypeDescriptionDefault
childrenReactNode[] | ReactNode[]The checkboxes items.-
orientationvertical | horizontalThe axis the checkbox group items should align with.vertical
colordefault | primary | secondary | success | warning | dangerThe color of the checkboxes.primary
sizexs | sm | md | lg | xlThe size of the checkboxes.md
radiusnone | base | xs | sm | md | lg | xl | fullThe radius of the checkboxes.md
namestringThe name of the CheckboxGroup, used when submitting an HTML form.-
labelstringThe label of the CheckboxGroup.-
valuestring[]The current selected values. (controlled).-
lineThroughbooleanWhether the checkboxes label should be crossed out.false
defaultValuestring[]The default selected values. (uncontrolled).-
isInvalidbooleanWhether the checkbox group is invalid.false
validationStatevalid | invalidWhether the inputs should display its "valid" or "invalid" visual styling. (Deprecated) use isInvalid instead.-
descriptionReactNodeThe checkbox group description.-
errorMessageReactNode | ((v: ValidationResult) => ReactNode)The checkbox group error message.-
validate(value: string[]) => ValidationError | true | null | undefinedValidate 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.-
validationBehaviornative | ariaWhether 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
isDisabledbooleanWhether the checkbox group is disabled.false
isRequiredbooleanWhether user checkboxes are required on the input before form submission.false
isReadOnlybooleanWhether the checkboxes can be selected but not changed by the user.-
disableAnimationbooleanWhether the animation should be disabled.false
classNamesRecord<"base"| "wrapper"| "label", string>Allows to set custom class names for the checkbox group slots.-

Checkbox Group Events

AttributeTypeDescription
onChange(value: string[]) => voidHandler that is called when the value changes.