https://github.com/accessible-ui/radio
🅰 An accessible and versatile radio component for React
https://github.com/accessible-ui/radio
a11y a11y-radio a11y-radiogroup a11y-react accessible-radio accessible-radiogroup accessible-react aria aria-radio aria-radio-component radiogroup react react-radiogroup
Last synced: 8 months ago
JSON representation
🅰 An accessible and versatile radio component for React
- Host: GitHub
- URL: https://github.com/accessible-ui/radio
- Owner: accessible-ui
- License: mit
- Created: 2019-12-17T22:01:09.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-06T02:21:29.000Z (about 3 years ago)
- Last Synced: 2025-06-01T00:03:28.456Z (9 months ago)
- Topics: a11y, a11y-radio, a11y-radiogroup, a11y-react, accessible-radio, accessible-radiogroup, accessible-react, aria, aria-radio, aria-radio-component, radiogroup, react, react-radiogroup
- Language: TypeScript
- Homepage: https://codesandbox.io/s/accessibleradio-examples-olksf
- Size: 2.65 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
<Radio>
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**](https://codesandbox.io/s/accessibleradio-examples-olksf)
```jsx harmony
import {RadioGroup, Radio, Mark} from '@accessible/radio'
const MyRadio = () => (
What is your favorite food?
Pizza
Tacos
)
```
## 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`](#radio) inputs |
### useRadioGroup()
A React hook that returns the [`RadioGroupContextValue`](#radiogroupcontextvalue) for the nearest `` parent.
### RadioGroupContextValue
```typescript
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 ``. 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 `` component is checked/unchecked. It must be a child of a ``.
#### 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 `` is in
a `checked` state. It must be a child of a ``.
#### 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 `` is in
an `unchecked` state. It must be a child of a ``.
#### 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`](#radiocontextvalue) for the nearest `` parent.
### RadioContextValue
```typescript
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