Skip to main content
Reakit
DocumentationNewsletter
GitHub
GitHub

Radio

Accessible Radio component that follows the WAI-ARIA Radio Button/Group Pattern.

#Installation

npm install reakit

Learn more in Get started.

#Usage

import { useRadioState, Radio, RadioGroup } from "reakit/Radio";

function Example() {
  const radio = useRadioState();
  return (
    <RadioGroup {...radio} aria-label="fruits">
      <label>
        <Radio {...radio} value="apple" /> apple
      </label>
      <label>
        <Radio {...radio} value="orange" /> orange
      </label>
      <label>
        <Radio {...radio} value="watermelon" /> watermelon
      </label>
    </RadioGroup>
  );
}

#Default value

To set a default value, you can pass the value of the current checked radio to the state property on useRadioState.

import { useRadioState, Radio, RadioGroup } from "reakit/Radio";

function Example() {
  const radio = useRadioState({ state: "orange" });
  return (
    <RadioGroup {...radio} aria-label="fruits">
      <label>
        <Radio {...radio} value="apple" /> apple
      </label>
      <label>
        <Radio {...radio} value="orange" /> orange
      </label>
      <label>
        <Radio {...radio} value="watermelon" /> watermelon
      </label>
    </RadioGroup>
  );
}

#Accessibility

  • Radio has role radio.
  • Radio has aria-checked set to true when it's checked. Otherwise, aria-checked is set to false.
  • Radio extends the accessibility features of CompositeItem, which means it uses the roving tabindex method to manage focus.

Learn more in Accessibility.

#Composition

Learn more in Composition.

#Props

#useRadioState

  • baseId string

    ID that will serve as a base for all the items IDs.

  • unstable_virtual boolean

    If enabled, the composite element will act as an aria-activedescendant container instead of roving tabindex. DOM focus will remain on the composite while its items receive virtual focus.

  • rtl boolean

    Determines how next and previous functions will behave. If rtl is set to true, they will be inverted. You still need to set dir="rtl" on HTML/CSS.

  • orientation "horizontal" | "vertical" | undefined

    Defines the orientation of the composite widget. If the composite has a single row or column (one-dimensional), the orientation value determines which arrow keys can be used to move focus:

    • undefined: all arrow keys work.
    • horizontal: only left and right arrow keys work.
    • vertical: only up and down arrow keys work.

    It doesn't have any effect on two-dimensional composites.

  • currentId string | null | undefined

    The current focused item id.

    • undefined will automatically focus the first enabled composite item.
    • null will focus the composite container and users will be able to navigate out of it using arrow keys.
    • If currentId is initially set to null, the composite element itself will have focus and users will be able to navigate to it using arrow keys.
  • loop boolean | "horizontal" | "vertical"

    On one-dimensional composites:

    • true loops from the last item to the first item and vice-versa.
    • horizontal loops only if orientation is horizontal or not set.
    • vertical loops only if orientation is vertical or not set.
    • If currentId is initially set to null, the composite element will be focused in between the last and first items.

    On two-dimensional composites:

    • true loops from the last row/column item to the first item in the same row/column and vice-versa. If it's the last item in the last row, it moves to the first item in the first row and vice-versa.
    • horizontal loops only from the last row item to the first item in the same row.
    • vertical loops only from the last column item to the first item in the column row.
    • If currentId is initially set to null, vertical loop will have no effect as moving down from the last row or up from the first row will focus the composite element.
    • If wrap matches the value of loop, it'll wrap between the last item in the last row or column and the first item in the first row or column and vice-versa.
  • wrap boolean | "horizontal" | "vertical"

    If enabled, moving to the next item from the last one in a row or column will focus the first item in the next row or column and vice-versa.

    • true wraps between rows and columns.
    • horizontal wraps only between rows.
    • vertical wraps only between columns.
    • If loop matches the value of wrap, it'll wrap between the last item in the last row or column and the first item in the first row or column and vice-versa.
  • state string | number | undefined

    The value attribute of the current checked radio.

#Radio

  • disabled boolean | undefined

    Same as the HTML attribute.

  • focusable boolean | undefined

    When an element is disabled, it may still be focusable. It works similarly to readOnly on form elements. In this case, only aria-disabled will be set.

  • id string | undefined

    Same as the HTML attribute.

  • value string | number

    Same as the value attribute.

  • checked boolean | undefined

    Same as the checked attribute.

17 state props

These props are returned by the state hook. You can spread them into this component ({...state}) or pass them separately. You can also provide these props from your own state logic.

  • baseId string

    ID that will serve as a base for all the items IDs.

  • unstable_virtual boolean

    If enabled, the composite element will act as an aria-activedescendant container instead of roving tabindex. DOM focus will remain on the composite while its items receive virtual focus.

  • orientation "horizontal" | "vertical" | undefined

    Defines the orientation of the composite widget. If the composite has a single row or column (one-dimensional), the orientation value determines which arrow keys can be used to move focus:

    • undefined: all arrow keys work.
    • horizontal: only left and right arrow keys work.
    • vertical: only up and down arrow keys work.

    It doesn't have any effect on two-dimensional composites.

  • unstable_moves number

    Stores the number of moves that have been performed by calling move, next, previous, up, down, first or last.

  • currentId string | null | undefined

    The current focused item id.

    • undefined will automatically focus the first enabled composite item.
    • null will focus the composite container and users will be able to navigate out of it using arrow keys.
    • If currentId is initially set to null, the composite element itself will have focus and users will be able to navigate to it using arrow keys.
  • items Item[]

    Lists all the composite items with their id, DOM ref, disabled state and groupId if any. This state is automatically updated when registerItem and unregisterItem are called.

  • registerItem (item: Item) => void

    Registers a composite item.

  • unregisterItem (id: string) => void

    Unregisters a composite item.

  • setCurrentId (value: SetStateAction<string | null | undefine...

    Sets currentId.

  • next (unstable_allTheWay?: boolean | undefined) => void

    Moves focus to the next item.

  • previous (unstable_allTheWay?: boolean | undefined) => void

    Moves focus to the previous item.

  • up (unstable_allTheWay?: boolean | undefined) => void

    Moves focus to the item above.

  • down (unstable_allTheWay?: boolean | undefined) => void

    Moves focus to the item below.

  • first () => void

    Moves focus to the first item.

  • last () => void

    Moves focus to the last item.

  • state string | number | undefined

    The value attribute of the current checked radio.

  • setState (value: SetStateAction<string | number | undefi...

    Sets state.

#RadioGroup

  • disabled boolean | undefined

    Same as the HTML attribute.

  • focusable boolean | undefined

    When an element is disabled, it may still be focusable. It works similarly to readOnly on form elements. In this case, only aria-disabled will be set.

12 state props

These props are returned by the state hook. You can spread them into this component ({...state}) or pass them separately. You can also provide these props from your own state logic.

  • baseId string

    ID that will serve as a base for all the items IDs.

  • unstable_virtual boolean

    If enabled, the composite element will act as an aria-activedescendant container instead of roving tabindex. DOM focus will remain on the composite while its items receive virtual focus.

  • orientation "horizontal" | "vertical" | undefined

    Defines the orientation of the composite widget. If the composite has a single row or column (one-dimensional), the orientation value determines which arrow keys can be used to move focus:

    • undefined: all arrow keys work.
    • horizontal: only left and right arrow keys work.
    • vertical: only up and down arrow keys work.

    It doesn't have any effect on two-dimensional composites.

  • currentId string | null | undefined

    The current focused item id.

    • undefined will automatically focus the first enabled composite item.
    • null will focus the composite container and users will be able to navigate out of it using arrow keys.
    • If currentId is initially set to null, the composite element itself will have focus and users will be able to navigate to it using arrow keys.
  • wrap boolean | "horizontal" | "vertical"

    If enabled, moving to the next item from the last one in a row or column will focus the first item in the next row or column and vice-versa.

    • true wraps between rows and columns.
    • horizontal wraps only between rows.
    • vertical wraps only between columns.
    • If loop matches the value of wrap, it'll wrap between the last item in the last row or column and the first item in the first row or column and vice-versa.
  • unstable_moves number

    Stores the number of moves that have been performed by calling move, next, previous, up, down, first or last.

  • groups Group[]

    Lists all the composite groups with their id and DOM ref. This state is automatically updated when registerGroup and unregisterGroup are called.

  • items Item[]

    Lists all the composite items with their id, DOM ref, disabled state and groupId if any. This state is automatically updated when registerItem and unregisterItem are called.

  • setCurrentId (value: SetStateAction<string | null | undefine...

    Sets currentId.

  • first () => void

    Moves focus to the first item.

  • last () => void

    Moves focus to the last item.

  • move (id: string | null) => void

    Moves focus to a given item ID.