useRadioGroupState

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

install	`yarn add react-stately`
version	3.33.1
usage	`import {useRadioGroupState} from 'react-stately'`

View repository

GitHub

View package

NPM

API#

useRadioGroupState(
  (props: RadioGroupProps
)): RadioGroupState

Interface#

Properties

Name	Type	Description
`isDisabled`	`boolean`	Whether the radio group is disabled.
`isReadOnly`	`boolean`	Whether the radio group is read only.
`isRequired`	`boolean`	Whether the radio group is required.
`isInvalid`	`boolean`	Whether the radio group is invalid.
`selectedValue`	`string \| null`	The currently selected value.
`lastFocusedValue`	`string \| null`	The value of the last focused radio.
`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.

Methods

Method	Description
`setSelectedValue( (value: string \| \| null )): void`	Sets the selected value.
`setLastFocusedValue( (value: string \| \| null )): void`	Sets the last focused value.
`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.

Example#

See the docs for useRadioGroup in react-aria for an example of useRadioGroupState.

Name	Type	Default	Description
`orientation`	`Orientation`	`'vertical'`	The axis the Radio Button(s) should align with.
`value`	`string \| null`	—	The current value (controlled).
`defaultValue`	`string \| null`	—	The default value (uncontrolled).
`onChange`	`( (value: string )) => void`	—	Handler that is called when the value changes.
`isDisabled`	`boolean`	—	Whether the input is disabled.
`isReadOnly`	`boolean`	—	Whether the input can be selected but not changed by the user.
`name`	`string`	—	The name of the input element, used when submitting an HTML form. See MDN.
`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 \| \| null )) => 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.
`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.
`onFocus`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.

'horizontal' | 'vertical'

'valid' | 'invalid'

string | string[]

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.

Properties

Name	Type	Description
`isDisabled`	`boolean`	Whether the radio group is disabled.
`isReadOnly`	`boolean`	Whether the radio group is read only.
`isRequired`	`boolean`	Whether the radio group is required.
`isInvalid`	`boolean`	Whether the radio group is invalid.
`selectedValue`	`string \| null`	The currently selected value.
`lastFocusedValue`	`string \| null`	The value of the last focused radio.
`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.

Methods

Method	Description
`setSelectedValue( (value: string \| \| null )): void`	Sets the selected value.
`setLastFocusedValue( (value: string \| \| null )): void`	Sets the last focused value.
`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.