@palmerhq/radio-group

An accessible WAI-ARIA 1.1-compliant Radio Group React component.

• @palmerhq/radio-group
  • Installation
  • Usage
    • Usage with Formik v2
  • API Reference
    • <RadioGroup />
      • labelledBy?: string
      • onChange: (value: any) => void
      • children: React.ComponentType<RadioProps>[]
      • value: any
      • as?: React.ComponentType
      • autoFocus?: boolean
    • <Radio>
      • value: any
      • onFocus?: () => void
      • onBlur?: () => void
      • as?: React.ComponentType
    • Underlying DOM Structure
    • Overriding Styles
  • Accessibility Features
  • Authors

Installation

yarn add @palmerhq/radio-group

Or try it out in your browser on CodeSandbox

Note: This package uses Array.prototype.findIndex, so be sure that you have properly polyfilled.

Usage

import * as React from 'react';
import { RadioGroup, Radio } from '@palmerhq/radio-group';
import '@palmerhq/radio-group/styles.css'; // use the default styles

function App() {
  const [value, setValue] = React.useState<string | undefined>();

  return (
    <>
      <h3 id="color">Color</h3>
      <RadioGroup
        labelledBy="color"
        value={value}
        onChange={value => setValue(value)}
      >
        <Radio value="blue">Blue</Radio>
        <Radio value="red">Red</Radio>
        <Radio value="green">Green</Radio>
      </RadioGroup>
    </>
  );
}

Usage with Formik v2

import * as React from 'react';
import { Formik, Form, useField } from 'formik';
import { RadioGroup, Radio } from '@palmerhq/radio-group';
import '@palmerhq/radio-group/styles.css'; // use the default styles

function FRadioGroup(props) {
  const [{ onChange, onBlur, ...field }] = useField(props.name);
  return (
    <RadioGroup
      {...props}
      {...field}
      labelledBy={props.name}
      onBlur={onBlur(props.name)}
      onChange={onChange(props.name)}
    />
  );
}

function App() {
  return (
    <Formik
      initialValues={{ color: '' }}
      validationSchema={Yup.object().shape({
        color: Yup.string().required(),
      })}
      onSubmit={(values, { setSubmitting }) => {
        setTimeout(() => {
          alert(JSON.stringify(values, null, 2));
          setSubmitting(false);
        }, 500);
      }}
    >
      <Form>
        <h3 id="color">Color</h3>
        <FRadioGroup name="color">
          <Radio value="blue">Blue</Radio>
          <Radio value="red">Red</Radio>
          <Radio value="green">Green</Radio>
        </FRadioGroup>
      </Form>
    </Formik>
  );
}

API Reference

<RadioGroup />

This renders a div and will pass through all props to the DOM element. It's children must be <Radio> components.

labelledBy?: string

This should match the id you used to label the radio group.

<h3 id="color">Color</h3>
<RadioGroup labelledBy="color">
  {/* ... */}
</RadioGroup>

onChange: (value: any) => void

A callback function that will be fired with the value of the newly selected item.

import * as React from 'react';
import { RadioGroup, Radio } from '@palmerhq/radio-group';
import '@palmerhq/radio-group/styles.css'; // use the default styles

function App() {
  const [value, setValue] = React.useState<string | undefined>();

  return (
    <>
      <h3 id="color">Color</h3>
      <RadioGroup
        labelledBy="color"
        value={value}
        onChange={value => setValue(value)}
      >
        <Radio value="blue">Blue</Radio>
        <Radio value="red">Red</Radio>
        <Radio value="green">Green</Radio>
      </RadioGroup>
    </>
  );
}

children: React.ComponentType<RadioProps>[]

Required

The children of a <RadioGroup> can ONLY be <Radio> components. In order to support compliant keyboard behavior, each sibling must know the value of the whole group and so React.Children.map is used internally.

<h3 id="color">Color</h3>
<RadioGroup labelledBy="color">
  {/* ... */}
</RadioGroup>

value: any

Required

The current value of the radio group. This is shallowly compared to each value prop of the child <Radio> components to determine which item is active.

as?: React.ComponentType

Component to use a the wrapper. Default is <div>.

autoFocus?: boolean

Whether to autoFocus the selected radio option.

<Radio>

This renders a div with a data attribute data-palmerhq-radio and all the relevant perfect aria attributes. The React component will pass through all props to the DOM element.

value: any

Required

The value of the radio button. This will be set / passed back to the <RadioGroup onChange> when the item is selected.

onFocus?: () => void

Callback function for when the item is focused. When focused, a data attribute data-palmerhq-radio-focus is set to "true". You can thus apply the selector to manage focus style like so:

[data-palmerhq-radio][data-palmerhq-radio-focus='true'] {
  background: blue;
}

onBlur?: () => void

Callback function for when the item is blurred

as?: React.ComponentType

Component to use as radio. Default is <div>.

Underlying DOM Structure

For reference, the underlying HTML DOM structure are all divs and looks as follows.

<div role="radiogroup" aria-labelledby="color" data-palmerhq-radio-group="true">
  <div
    role="radio"
    tabindex="0"
    aria-checked="false"
    data-palmerhq-radio="true"
    data-palmerhq-radio-focus="false"
  >
    Red
  </div>
  <div
    role="radio"
    tabindex="-1"
    aria-checked="false"
    data-palmerhq-radio="true"
    data-palmerhq-radio-focus="false"
  >
    Green
  </div>
  <div
    role="radio"
    tabindex="-1"
    aria-checked="false"
    data-palmerhq-radio="true"
    data-palmerhq-radio-focus="false"
  >
    Blue
  </div>
</div>

Overriding Styles

These are the default styles. Copy and paste the following into your app to customize them.

[data-palmerhq-radio-group] {
  padding: 0;
  margin: 0;
  list-style: none;
}

[data-palmerhq-radio-group]:focus {
  outline: none;
}

[data-palmerhq-radio] {
  border: 2px solid transparent;
  border-radius: 5px;
  display: inline-block;
  position: relative;
  padding: 0.125em;
  padding-left: 1.5em;
  padding-right: 0.5em;
  cursor: default;
  outline: none;
}

[data-palmerhq-radio] + [data-palmerhq-radio] {
  margin-left: 1em;
}

[data-palmerhq-radio]::before,
[data-palmerhq-radio]::after {
  position: absolute;
  top: 50%;
  left: 7px;
  transform: translate(-20%, -50%);
  content: '';
}

[data-palmerhq-radio]::before {
  width: 14px;
  height: 14px;
  border: 1px solid hsl(0, 0%, 66%);
  border-radius: 100%;
  background-image: linear-gradient(to bottom, hsl(300, 3%, 93%), #fff 60%);
}

[data-palmerhq-radio]:active::before {
  background-image: linear-gradient(
    to bottom,
    hsl(300, 3%, 73%),
    hsl(300, 3%, 93%)
  );
}

[data-palmerhq-radio][aria-checked='true']::before {
  border-color: hsl(216, 80%, 50%);
  background: hsl(217, 95%, 68%);
  background-image: linear-gradient(
    to bottom,
    hsl(217, 95%, 68%),
    hsl(216, 80%, 57%)
  );
}

[data-palmerhq-radio][aria-checked='true']::after {
  display: block;
  border: 0.1875em solid #fff;
  border-radius: 100%;
  transform: translate(25%, -50%);
}

[data-palmerhq-radio][aria-checked='mixed']:active::before,
[data-palmerhq-radio][aria-checked='true']:active::before {
  background-image: linear-gradient(
    to bottom,
    hsl(216, 80%, 57%),
    hsl(217, 95%, 68%) 60%
  );
}

[data-palmerhq-radio]:hover::before {
  border-color: hsl(216, 94%, 65%);
}

[data-palmerhq-radio][data-palmerhq-radio-focus='true'] {
  border-color: hsl(216, 94%, 73%);
  background-color: hsl(216, 80%, 97%);
}

[data-palmerhq-radio]:hover {
  background-color: hsl(216, 80%, 92%);
}

Accessibility Features

• Uses CSS attribute selectors for synchronizing aria-checked state with the visual state indicator.
• Uses CSS :hover and :focus pseudo-selectors for styling visual keyboard focus and hover.
• Focus indicator encompasses both radio button and label, making it easier to perceive which option is being chosen.
• Hover changes background of both radio button and label, making it easier to perceive that clicking either the label or button will activate the radio button.

Keyboard Support

Role, Property, State, and Tabindex Attributes

Authors

• Jared Palmer (@jaredpalmer)

MIT License