CheckboxGroup

Copy for LLM

A checkbox group allows a user to select one or multiple checkbox items.

Import

import { CheckboxGroup, Checkbox } from "@cfa/react-core";

Live Editor

Examples

Disabled

The isDisabled prop applies the following visual style and prevents the user from making a selection.

Description

The description prop provides additional context to the user about the checkbox group or individual checkboxes. You may pass the description prop to the CheckboxGroup or Checkbox component.

Readonly

The isReadOnly prop applies the following visual style and prevents the user from making a selection.

Required

The isRequired prop adds a red asterisk to the checkbox group label.

Success

The isSuccess prop should be used conditionally on the individual Checkbox, not all checkboxes in a group.

Controlled

Use the value or defaultValue prop to set the selected items, and onChange to handle selection changes.

Validation

For validation, pass the isRequired prop and add a custom errorMessage.

Click submit with no selection made to get errorMessage.

Props

Visit the Documentation Site for the full list of props.

CheckboxGroup

Name	Type	Default	Description
children	`ReactNode`	-	The children checkboxes of the checkbox group.
description	`string`	-	The helper text for the checkbox group.
errorMessage	`string \| ((validation: ValidationResult) => string)`	-	Error message displays when the checkbox group is invalid.
label	`string`	-	The label of the checkbox group.
ref	`Ref<HTMLDivElement>`	-	Requires React 19
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.
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.
className	`ClassNameOrFunction<CheckboxGroupRenderProps>`	`'react-aria-CheckboxGroup'`	The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state.
defaultValue	`string[]`	-	The default value (uncontrolled).
dir	`string`	-	-
form	`string`	-	The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form).
hidden	`boolean`	-	-
id	`string`	-	The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).
inert	`boolean`	-	-
isDisabled	`boolean`	-	Whether the input is disabled.
isInvalid	`boolean`	-	Whether the input value is invalid.
isReadOnly	`boolean`	-	Whether the input can be selected but not changed by the user.
isRequired	`boolean`	-	Whether user input is required on the input before form submission.
lang	`string`	-	-
name	`string`	-	The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname).
onAnimationEnd	`AnimationEventHandler<HTMLDivElement>`	-	-
onAnimationEndCapture	`AnimationEventHandler<HTMLDivElement>`	-	-
onAnimationIteration	`AnimationEventHandler<HTMLDivElement>`	-	-
onAnimationIterationCapture	`AnimationEventHandler<HTMLDivElement>`	-	-
onAnimationStart	`AnimationEventHandler<HTMLDivElement>`	-	-
onAnimationStartCapture	`AnimationEventHandler<HTMLDivElement>`	-	-
onAuxClick	`MouseEventHandler<HTMLDivElement>`	-	-
onAuxClickCapture	`MouseEventHandler<HTMLDivElement>`	-	-
onBlur	`(e: FocusEvent<Element, Element>) => void`	-	Handler that is called when the element loses focus.
onChange	`(value: string[]) => void`	-	Handler that is called when the value changes.
onClick	`MouseEventHandler<HTMLDivElement>`	-	-
onClickCapture	`MouseEventHandler<HTMLDivElement>`	-	-
onContextMenu	`MouseEventHandler<HTMLDivElement>`	-	-
onContextMenuCapture	`MouseEventHandler<HTMLDivElement>`	-	-
onDoubleClick	`MouseEventHandler<HTMLDivElement>`	-	-
onDoubleClickCapture	`MouseEventHandler<HTMLDivElement>`	-	-
onFocus	`(e: FocusEvent<Element, Element>) => void`	-	Handler that is called when the element receives focus.
onFocusChange	`(isFocused: boolean) => void`	-	Handler that is called when the element's focus status changes.
onGotPointerCapture	`PointerEventHandler<HTMLDivElement>`	-	-
onGotPointerCaptureCapture	`PointerEventHandler<HTMLDivElement>`	-	-
onLostPointerCapture	`PointerEventHandler<HTMLDivElement>`	-	-
onLostPointerCaptureCapture	`PointerEventHandler<HTMLDivElement>`	-	-
onMouseDown	`MouseEventHandler<HTMLDivElement>`	-	-
onMouseDownCapture	`MouseEventHandler<HTMLDivElement>`	-	-
onMouseEnter	`MouseEventHandler<HTMLDivElement>`	-	-
onMouseLeave	`MouseEventHandler<HTMLDivElement>`	-	-
onMouseMove	`MouseEventHandler<HTMLDivElement>`	-	-
onMouseMoveCapture	`MouseEventHandler<HTMLDivElement>`	-	-
onMouseOut	`MouseEventHandler<HTMLDivElement>`	-	-
onMouseOutCapture	`MouseEventHandler<HTMLDivElement>`	-	-
onMouseOver	`MouseEventHandler<HTMLDivElement>`	-	-
onMouseOverCapture	`MouseEventHandler<HTMLDivElement>`	-	-
onMouseUp	`MouseEventHandler<HTMLDivElement>`	-	-
onMouseUpCapture	`MouseEventHandler<HTMLDivElement>`	-	-
onPointerCancel	`PointerEventHandler<HTMLDivElement>`	-	-
onPointerCancelCapture	`PointerEventHandler<HTMLDivElement>`	-	-
onPointerDown	`PointerEventHandler<HTMLDivElement>`	-	-
onPointerDownCapture	`PointerEventHandler<HTMLDivElement>`	-	-
onPointerEnter	`PointerEventHandler<HTMLDivElement>`	-	-
onPointerLeave	`PointerEventHandler<HTMLDivElement>`	-	-
onPointerMove	`PointerEventHandler<HTMLDivElement>`	-	-
onPointerMoveCapture	`PointerEventHandler<HTMLDivElement>`	-	-
onPointerOut	`PointerEventHandler<HTMLDivElement>`	-	-
onPointerOutCapture	`PointerEventHandler<HTMLDivElement>`	-	-
onPointerOver	`PointerEventHandler<HTMLDivElement>`	-	-
onPointerOverCapture	`PointerEventHandler<HTMLDivElement>`	-	-
onPointerUp	`PointerEventHandler<HTMLDivElement>`	-	-
onPointerUpCapture	`PointerEventHandler<HTMLDivElement>`	-	-
onScroll	`UIEventHandler<HTMLDivElement>`	-	-
onScrollCapture	`UIEventHandler<HTMLDivElement>`	-	-
onTouchCancel	`TouchEventHandler<HTMLDivElement>`	-	-
onTouchCancelCapture	`TouchEventHandler<HTMLDivElement>`	-	-
onTouchEnd	`TouchEventHandler<HTMLDivElement>`	-	-
onTouchEndCapture	`TouchEventHandler<HTMLDivElement>`	-	-
onTouchMove	`TouchEventHandler<HTMLDivElement>`	-	-
onTouchMoveCapture	`TouchEventHandler<HTMLDivElement>`	-	-
onTouchStart	`TouchEventHandler<HTMLDivElement>`	-	-
onTouchStartCapture	`TouchEventHandler<HTMLDivElement>`	-	-
onTransitionCancel	`TransitionEventHandler<HTMLDivElement>`	-	-
onTransitionCancelCapture	`TransitionEventHandler<HTMLDivElement>`	-	-
onTransitionEnd	`TransitionEventHandler<HTMLDivElement>`	-	-
onTransitionEndCapture	`TransitionEventHandler<HTMLDivElement>`	-	-
onTransitionRun	`TransitionEventHandler<HTMLDivElement>`	-	-
onTransitionRunCapture	`TransitionEventHandler<HTMLDivElement>`	-	-
onTransitionStart	`TransitionEventHandler<HTMLDivElement>`	-	-
onTransitionStartCapture	`TransitionEventHandler<HTMLDivElement>`	-	-
onWheel	`WheelEventHandler<HTMLDivElement>`	-	-
onWheelCapture	`WheelEventHandler<HTMLDivElement>`	-	-
render	`DOMRenderFunction<"div", CheckboxGroupRenderProps>`	-	Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: * You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). * Only a single root DOM element can be rendered (no fragments). * You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
slot	`string`	-	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.
style	`StyleOrFunction<CheckboxGroupRenderProps>`	-	The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state.
translate	`"yes" \| "no"`	-	-
validate	`(value: string[]) => true \| ValidationError`	-	A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead.
validationBehavior	`"native" \| "aria"`	`'native'`	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.
value	`string[]`	-	The current value (controlled).