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';

Default

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

Row

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

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.

Events

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.

APIs

Checkbox Group Props

Attribute	Type	Description	Default
children*	CheckboxGroupChildren	The Checkboxes contained within the checkbox group.	-
label	`ReactNode`	The content to display as the label.	-
value	`string[]`	The current value (controlled).	-
defaultValue	`string[]`	The current value (uncontrolled).	-
name	`string`	The name of the checkbox group, used when submitting an HTML form.	-
orientation	`horizontal` `vertical`	The axis the checkbox group items should align with.	`vertical`
size	NormalSizes	The size of the component	`medium`
color	NormalColors	The color of the component	`default`
labelColor	SimpleColors	The color of the label	`default`
isDisabled	`boolean`	Whether the checkbox group is disabled	`false`
isReadOnly	`boolean`	Whether the input can be selected but not changed by the user.	`false`
css	`Stitches.CSS`	Override Default CSS style	-
as	`keyof JSX.IntrinsicElements`	Changes which tag component outputs	`div`

Checkbox Group Events

Attribute	Type	Description	Default
onChange	`(value: T) => void`	Handler that is called when the value changes	-

Checkbox Group Accessibility Props

Attribute	Type	Description	Default
id	`string`	The element's unique identifier. See MDN	-
aria-label	`string`	Defines a string value that labels the current element	-
aria-labelledby	`string`	Identifies the element (or elements) that labels the current element	-
aria-describedby	`string`	Identifies the element (or elements) that describes the object.	-
aria-details	`string`	Identifies the element (or elements) that provide a detailed, extended description for the object.	-
aria-errormessage	`string`	Identifies 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';

Checkbox Radio

Created by Junior Garcia

Deployed on

Documentation