useToggleState

Provides state management for toggle components like checkboxes and switches.

install	`yarn add react-stately`
version	3.23.0
usage	`import {useToggleState} from 'react-stately'`

View repository

GitHub

View package

NPM

API#

useToggleState(
  (props: ToggleStateOptions
)): ToggleState

Interface#

Properties

Name	Type	Description
`isSelected`	`boolean`	Whether the toggle is selected.

Methods

Method	Description
`setSelected( (isSelected: boolean )): void`	Updates selection state.
`toggle(): void`	Toggle the selection state.

Example#

See the docs for useCheckbox in react-aria for an example of useToggleState.

Name	Type	Default	Description
`defaultSelected`	`boolean`	—	Whether the element should be selected (uncontrolled).
`isSelected`	`boolean`	—	Whether the element should be selected (controlled).
`onChange`	`( (isSelected: boolean )) => void`	—	Handler that is called when the element's selection state changes.
`value`	`string`	—	The value 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.
`validationState`	`ValidationState`	—	Whether the input should display its "valid" or "invalid" visual styling.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission. Often paired with the `necessityIndicator` prop to add a visual indicator to the input.
`validationBehavior`	`'aria' \| 'native'`	`'aria'`	Whether `isRequired` should use native HTML form validation to prevent form submission when a value is missing, or only mark the field as required via ARIA.
`onValidationChange`	`( (state: FormValidationEvent )) => void`	—	Handler that is called when input validation changes.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`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.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is released.

'valid' | 'invalid'

Name	Type	Description
`isInvalid`	`boolean`	Whether the input is invalid.
`errorMessage`	`string`	The current error message for the input if it is invalid, otherwise an empty string.
`validationDetails`	`ValidityState`	The native validation details for the input.

BaseEvent<ReactKeyboardEvent<any>>

SyntheticEvent & {stopPropagation: () => void,
continuePropagation: () => void
}

Properties

Name	Type	Description
`isSelected`	`boolean`	Whether the toggle is selected.

Methods

Method	Description
`setSelected( (isSelected: boolean )): void`	Updates selection state.
`toggle(): void`	Toggle the selection state.