Checkbox Group

A CheckboxGroup allows users to select one or more items from a list of choices.


NextUI exports 2 checkbox-related components:

  • CheckboxGroup: The root component, it wraps the label and the wrapper.
  • Checkbox: The checkbox component.





You can use the value and onValueChange properties to control the checkbox input value.



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


Checkbox Group Props

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
radiusnone | base | xs | sm | md | lg | xl | fullThe radius of the
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.-
errorMessageReactNodeThe checkbox group error message.-
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

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