Checkbox Group

A CheckboxGroup allows users to select one or more items from a list of choices. CheckboxGrup implementation is based on @react-aria/checkbox

import { Checkbox } from '@nextui-org/react';


Checkbox.Group accepts multiple Checkbox elements as children. Each Checkbox represents an option that can be selected, labeled by its children.


Checkbox groups are vertically oriented by default. The orientation prop can be used to change the orientation to horizontal.

Controlled vs Uncontrolled

An initial, uncontrolled value can be provided to the Checkbox.Group using the defaultValue prop. Alternatively, a controlled value can be provided using the value prop. Both of these props accept an array of selected items, which map to the value prop on each item.

Note: See React's documentation on uncontrolled components for more info.


Checkbox.Group accepts an onChange prop, which is triggered when a user adds or removes an item from the selection. The example below uses onChange to log how the user is interacting with the component.

A11y: If a visible label isn't specified for a Checkbox.Group, an aria-label must be provided for accessibility. If the field is labeled by a separate element, an aria-labelledby prop must be provided using the id of the labeling element instead. Checkbox elements within a group should always have a visible label.


Checkbox Group Props

children*CheckboxGroupChildrenThe Checkboxes contained within the checkbox group.-
labelReactNodeThe content to display as the label.-
valuestring[]The current value (controlled).-
defaultValuestring[]The current value (uncontrolled).-
namestringThe name of the checkbox group, used when submitting an HTML form.-
orientationhorizontal verticalThe axis the checkbox group items should align with.vertical
sizeNormalSizesThe size of the componentmedium
colorNormalColorsThe color of the componentdefault
labelColorSimpleColorsThe color of the labeldefault
isDisabledbooleanWhether the checkbox group is disabledfalse
isReadOnlybooleanWhether the input can be selected but not changed by the user.false
cssStitches.CSSOverride Default CSS style-
askeyof JSX.IntrinsicElementsChanges which tag component outputsdiv

Checkbox Group Events

onChange(value: T) => voidHandler that is called when the value changes-

Checkbox Group Accessibility Props

idstringThe element's unique identifier. See MDN-
aria-labelstringDefines a string value that labels the current element-
aria-labelledbystringIdentifies the element (or elements) that labels the current element-
aria-describedbystringIdentifies the element (or elements) that describes the object.-
aria-detailsstringIdentifies the element (or elements) that provide a detailed, extended description for the object.-
aria-errormessagestringIdentifies the element that provides an error message for the object.-

Checkbox Group types

Checkbox Group Children

type ReactElement<CheckboxProps> | ReactElement<CheckboxProps>[]

Normal Colors

type NormalColors =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'gradient';

Simple Colors

type SimpleColors =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error';

Normal Sizes

type NormalSizes = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
gradient blue backgroundgradient violet background