useCheckboxGroup

Provides the behavior and accessibility implementation for a checkbox group component. Checkbox groups allow users to select multiple items from a list of options.

Favorite sports

Soccer

Baseball

Basketball

Example

CheckboxGroup.tsx

CheckboxGroup.css

Checkbox.css

Example

CheckboxGroup.tsx

CheckboxGroup.css

Checkbox.css

import {CheckboxGroup, Checkbox} from './CheckboxGroup';

<CheckboxGroup label="Favorite sports">
  <Checkbox value="soccer" isDisabled>Soccer</Checkbox>
  <Checkbox value="baseball">Baseball</Checkbox>
  <Checkbox value="basketball">Basketball</Checkbox>
</CheckboxGroup>

API

<CheckboxGroup>
  <Label />
  <CheckboxField />
  <Text slot="description" />
  <FieldError />
</CheckboxGroup>

useCheckboxGroupState(props: CheckboxGroupProps): CheckboxGroupStateuseCheckboxGroup(props: AriaCheckboxGroupProps, state: CheckboxGroupState): CheckboxGroupAria

useCheckboxGroupItem(
  props: AriaCheckboxGroupItemProps,
state: CheckboxGroupState,
inputRef: RefObject<HTMLInputElement | null>
): CheckboxAria

CheckboxGroupState

Properties

Name	Type
`isDisabled`	`boolean`
Whether the checkbox group is disabled.
`isReadOnly`	`boolean`
Whether the checkbox group is read only.
`realtimeValidation`	`ValidationResult`
Realtime validation results, updated as the user edits the value.
`displayValidation`	`ValidationResult`
Currently displayed validation results, updated when the user commits their changes.

`value`	`readonly string[]`
Current selected values.
`defaultValue`	`readonly string[]`
Default selected values.

Methods

`isSelected(value: string): boolean`
Returns whether the given value is selected.
`setValue(value: string[]): void`
Sets the selected values.
`addValue(value: string): void`
Adds a value to the set of selected values.
`removeValue(value: string): void`
Removes a value from the set of selected values.
`toggleValue(value: string): void`
Toggles a value in the set of selected values.
`setInvalid(value: string, validation: ValidationResult): void`
Sets whether one of the checkboxes is invalid.
`updateValidation(result: ValidationResult): void`
Updates the current validation result. Not displayed to the user until `commitValidation` is called.
`resetValidation(): void`
Resets the displayed validation state to valid when the user resets the form.
`commitValidation(): void`
Commits the realtime validation so it is displayed to the user.

AriaCheckboxGroupProps

Name	Type
`isDisabled`	`boolean`
Whether the input is disabled.
`isReadOnly`	`boolean`
Whether the input can be selected but not changed by the user.

`value`	`string[]`
The current value (controlled).
`defaultValue`	`string[]`
The default value (uncontrolled).
`onChange`	`(value: T) => void`
Handler that is called when the value changes.

CheckboxGroupAria

Name	Type
`groupProps`	`DOMAttributes`
Props for the checkbox group wrapper element.
`labelProps`	`DOMAttributes`
Props for the checkbox group's visible label (if any).
`descriptionProps`	`DOMAttributes`
Props for the checkbox group description element, if any.
`errorMessageProps`	`DOMAttributes`
Props for the checkbox group error message element, if any.
`validationDetails`	`ValidityState`
The native validation details for the input.

AriaCheckboxGroupItemProps

Name	Type
`isIndeterminate`	`boolean`
Indeterminism is presentational only. The indeterminate visual representation remains regardless of user interaction.
`children`	`ReactNode`
The label for the element.
`isDisabled`	`boolean`
Whether the input is disabled.
`isReadOnly`	`boolean`
Whether the input can be selected but not changed by the user.

`onChange`	`(isSelected: boolean) => void`
Handler that is called when the element's selection state changes.