useCheckboxGroupState

Provides state management for a checkbox group component. Provides a name for the group, and manages selection and focus state.

install	`yarn add react-stately`
version	3.42.0
usage	`import {useCheckboxGroupState} from 'react-stately'`

API#

useCheckboxGroupState(
  (props: CheckboxGroupProps
)): CheckboxGroupState

Name	Type	Description
`value`	`readonly string[]`	Current selected values.
`defaultValue`	`readonly string[]`	Default selected values.
`isDisabled`	`boolean`	Whether the checkbox group is disabled.
`isReadOnly`	`boolean`	Whether the checkbox group is read only.
`isInvalid`	`boolean`	Whether the checkbox group is invalid.
`isRequired`	`boolean`	Whether the checkboxes in the group are required. This changes to false once at least one item is selected.
`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.

Method	Description
`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.

Name	Type	Default	Description
`value`	`string[]`	—	The current value (controlled).
`defaultValue`	`string[]`	—	The default value (uncontrolled).
`onChange`	`( (value: T )) => void`	—	Handler that is called when the value changes.
`name`	`string`	—	The name of the input element, used when submitting an HTML form. See MDN.
`isDisabled`	`boolean`	—	Whether the input is disabled.
`isReadOnly`	`boolean`	—	Whether the input can be selected but not changed by the user.
`label`	`ReactNode`	—	The content to display as the label.
`description`	`ReactNode`	—	A description for the field. Provides a hint such as specific requirements for what to choose.
`errorMessage`	`ReactNode \| ( (v: ValidationResult )) => ReactNode`	—	An error message for the field.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission.
`isInvalid`	`boolean`	—	Whether the input value is invalid.
`validationBehavior`	`'aria' \| 'native'`	`'aria'`	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.
`validate`	`( (value: string[] )) => ValidationError \| true \| null \| undefined`	—	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.

Name	Type	Description
`isInvalid`	`boolean`	Whether the input value is invalid.
`validationErrors`	`string[]`	The current error messages for the input if it is invalid, otherwise an empty array.
`validationDetails`	`ValidityState`	The native validation details for the input.

'valid' | 'invalid'

string | string[]

Name	Type	Description
`value`	`readonly string[]`	Current selected values.
`defaultValue`	`readonly string[]`	Default selected values.
`isDisabled`	`boolean`	Whether the checkbox group is disabled.
`isReadOnly`	`boolean`	Whether the checkbox group is read only.
`isInvalid`	`boolean`	Whether the checkbox group is invalid.
`isRequired`	`boolean`	Whether the checkboxes in the group are required. This changes to false once at least one item is selected.
`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.

Method	Description
`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.