@accessible/radio

🅰 An accessible and versatile radio component for React

Usage no npm install needed!

<script type="module">
  import accessibleRadio from 'https://cdn.skypack.dev/@accessible/radio';
</script>

README


<Radio>

Bundlephobia Types Code coverage Build status NPM Version MIT License

npm i @accessible/radio

An accessible radio component for React. This library allows you to create your own a radio with your own styles while maintaining the ability to focus and update a radio input with the keyboard.

Quick Start

Check out the example on CodeSandbox

import {RadioGroup, Radio, Mark} from '@accessible/radio'

const MyRadio = () => (
  <RadioGroup name='favorite_food' defaultValue='pizza'>
    <h2>What is your favorite food?</h2>

    <label>
      <Radio value='pizza'>
        <span className='my-radio'>
          <Mark checkedClass='checked' uncheckedClass='unchecked'>
            <span className='mark' />
          </Mark>
        </span>
      </Radio>
      Pizza
    </label>

    <label>
      <Radio value='tacos'>
        <span className='my-radio'>
          <Mark checkedClass='checked' uncheckedClass='unchecked'>
            <span className='mark' />
          </Mark>
        </span>
      </Radio>
      Tacos
    </label>
  </RadioGroup>
)

API

<RadioGroup>

Creates context that controls the child <Radio> components. This is also where you set controlled values and default values for the radio group.

Props

Prop Type Default Required? Description
name string undefined Yes The name of the checkbox group (applied to each child <Radio> input)
value value: string | number | string[] | undefined undefined No Makes the radio group a controlled component which can no longer be updated with the setValue control or any <Radio> controls. It should be the same as one of the values in the child <Radio> inputs.
defaultValue value: string | number | string[] | undefined undefined No This sets the default radio group value. It should be the same as one of the values in the child <Radio> inputs.
onChange (value: string | number | string[] | undefined) => any undefined No This callback fires each time the checked value changes
children React.ReactNode undefined No Any React nodes, including your Radio inputs

useRadioGroup()

A React hook that returns the RadioGroupContextValue for the nearest <RadioGroup> parent.

RadioGroupContextValue

interface RadioGroupContextValue {
  name: string
  value: string | number | string[] | undefined
  setValue: (
    value:
      | string``
      | number
      | string[]
      | undefined
      | ((
          current: string | number | string[] | undefined
        ) => string | number | string[] | undefined)
  ) => void
}

<Radio>

Creates a visually hidden radio input that is focusable and accessible via keyboard navigation. All props passed to this component are applied to the <input>. This also creates a context provider enabling the other components in this library to access the radio's state deep in the tree.

Props

Prop Type Default Required? Description
disabled boolean false No Disables this radio option
onChange (checked: boolean) => any undefined No Called each time the checked state of this option changes.
children React.ReactNode undefined No Your custom styled radio.

<Mark>

A convenient component for conditionally adding class names and styles when the <Radio> component is checked/unchecked. It must be a child of a <Radio>.

Props

Prop Type Default Required? Description
uncheckedClass string undefined No This class name will be applied to the child element when the radio is unchecked.
checkedClass string undefined No This class name will be applied to the child element when the radio is checked.
uncheckedStyle React.CSSProperties undefined No These styles will be applied to the child element when the radio is unchecked.
checkedStyle React.CSSProperties undefined No These styles name will be applied to the child element when the radio is checked.
children React.ReactNode undefined Yes The child you wish to render when the radio is checked.

<Checked>

The child of this component will only render when the <Radio> is in a checked state. It must be a child of a <Radio>.

Props

Prop Type Default Required? Description
children React.ReactNode undefined Yes The child you wish to render when the radio is checked.

<Unchecked>

The child of this component will only render when the <Radio> is in an unchecked state. It must be a child of a <Radio>.

Props

Prop Type Default Required? Description
children React.ReactNode undefined Yes The child you wish to render when the radio is unchecked.

useRadio()

A React hook that returns the RadioContextValue for the nearest <Radio> parent.

RadioContextValue

interface RadioContextValue {
  // Does the radio have a `checked` property?
  checked: boolean
  // Is the radio currently focused?
  focused: boolean
  // Is the radio currently disabled?
  disabled: boolean
  // Checks the radio
  check: () => void
  // Unchecks the radio
  uncheck: () => void
}

LICENSE

MIT