useRadioGroup

useRadioGroup is a custom hook that provides all the state management logic for a group of radios.

Import#

import { useRadioGroup } from '@chakra-ui/react'

Return value#

The useRadioGroup hook returns following props

Name	Type	Description
`value`	`StringOrNumber[]`	The value of radio group.
`name`	`string`	The name of the radio options. All radio options must use the same name.
`ref`	`any`	The ref of the radio group.
`isDisabled`	`boolean`	A utility to manage disabled state.
`isFocusable`	`boolean`	A utility to manage focused state.
`focus`	`() => void`	A utility function to set the focus on the first enabled radio.
`onChange`	`(nextValue: EventOrValue) => void`	The onChange handler for the radio group.
`setValue`	`(state: StringOrNumber[]) => void`	A function to set the value of the radio group.
`getRadioProps`	`(props?: Dict) => Dict`	A function that takes root props and handles changes for the radio group
`getRootProps`	`(props?: Dict) => Dict`	A function that takes radio root props and handles changes for the radio group
`htmlProps`	`{}`	A function that takes radio root props and handles changes for the radio group

Usage#

function Example() {
  function CustomRadio(props) {
    const { image, ...radioProps } = props
    const { state, getInputProps, getCheckboxProps, htmlProps, getLabelProps } =
      useRadio(radioProps)

    return (
      <chakra.label {...htmlProps} cursor='pointer'>
        <input {...getInputProps({})} hidden />
        <Box
          {...getCheckboxProps()}
          bg={state.isChecked ? 'green.200' : 'transparent'}
          w={12}
          p={1}
          rounded='full'
        >
          <Image src={image} rounded='full' {...getLabelProps()} />
        </Box>
      </chakra.label>
    )
  }

  const toast = useToast()

  const avatars = [
    { name: 'Kat', image: 'https://randomuser.me/api/portraits/women/44.jpg' },
    { name: 'Kevin', image: 'https://randomuser.me/api/portraits/men/86.jpg' },
    { name: 'Andy', image: 'https://randomuser.me/api/portraits/men/29.jpg' },
    { name: 'Jess', image: 'https://randomuser.me/api/portraits/women/95.jpg' },
  ]

  const handleChange = (value) => {
    toast({
      title: `The value got changed to ${value}!`,
      status: 'success',
      duration: 2000,
    })
  }

  const { value, getRadioProps, getRootProps } = useRadioGroup({
    defaultValue: 'Kevin',
    onChange: handleChange,
  })

  return (
    <Stack {...getRootProps()}>
      <Text>The selected radio is: {value}</Text>
      <HStack>
        {avatars.map((avatar) => {
          return (
            <CustomRadio
              key={avatar.name}
              image={avatar.image}
              {...getRadioProps({ value: avatar.name })}
            />
          )
        })}
      </HStack>
    </Stack>
  )
}

Parameters#

The useRadioGroup hook accepts an object with the following properties:

`defaultValue`

Description

The value of the radio to be checked initially (in uncontrolled mode)

Type

StringOrNumber

`isDisabled`

Description

If true, all wrapped radio inputs will be disabled

Type

boolean

`isFocusable`

Description

If true and isDisabled is true, all wrapped radio inputs will remain focusable but not interactive.

Type

boolean

`isNative`

Description

If true, input elements will receive checked attribute instead of isChecked. This assumes, you're using native radio inputs

Type

boolean

`name`

Description

The name attribute forwarded to each radio element

Type

string

`onChange`

Description

Function called once a radio is checked @param nextValue the value of the checked radio

Type

((nextValue: string) => void)

`value`

Description

The value of the radio to be checked (in controlled mode)

Type

StringOrNumber