Stable

Radio Button

A radio button is used in select scenarios where a conventially styled radio button does not suit the required interaction. Radio buttons should be wrapped in a radio group container.

GitHub, opens in a new tab·Storybook, opens in a new tab·Playroom, opens in a new tab

Installation

bash

npm install @nib-components/radio-button

As a form input, @nib-components/form-control must wrap this component to provide an accessible label, help text, and validation styling. Note: You will also need to install the peerDependencies @nib/icons and @nib-components/theme.

Usage

jsx

import RadioButton from '@nib-components/radio-button';

You are more likely to use this component in conjunction with FormControl and RadioGroup:

jsx

<FormControl id="colour" name="colour" label="What's your favourite colour?" valid={false} validated={false} error="Please choose a colour.">
  <RadioGroup options={{g: 'Green', b: 'Blue'}} component={RadioButton} />
</FormControl>

<FormControl id="colour" name="colour" label="What's your favourite colour?" valid={false} validated={false} error="Please choose a colour.">
  <RadioGroup options={{g: 'Green', b: 'Blue'}} component={RadioButton} />
</FormControl>

Interactive demo

jsx

<>
  <RadioButton label="Green" subtitle="Like the grass" id="color-green" name="color" selected value="g" />
  <RadioButton label="Blue" subtitle="Like the sky" id="color-blue" name="color" value="b" disabled />
</>

<>
  <RadioButton label="Green" subtitle="Like the grass" id="color-green" name="color" selected value="g" />
  <RadioButton label="Blue" subtitle="Like the sky" id="color-blue" name="color" value="b" disabled />
</>

Props

Prop	Type	Default	Description
`id` (required)	string		The `input` id.
`name` (required)	string		The `input` name.
`value` (required)	string		The `input` value.
`label` (required)	string		The `input` label.
`subtitle`	string		The radio input subtitle.
`boldLabel`	boolean	`false`	Whether the label is bold. If subtitle is provided, the default value changes to `true`.
`selected`	boolean	`false`	Whether the `input` is selected.
`disabled`	boolean	`false`	Whether the `input` is disabled.
`inline`	boolean	`true`	Whether the `input` is displayed inline above the `sm` breakpoint. Set to `false` to remain stacked for all screens.
`formMode` (deprecated)	string	Defined by the theme	Can be one of `"white"` or `"light"`. Mode support has been shifted to the `ModeProvider` component instead of here.

In addition to these props, all other props passed to <RadioButton /> will be applied to the underlying <input> as attributes.

Considerations

A radio button is best used as part of an interface and should not be used within a form for gathering user data.

Preselect a default option unless it's important to not influence the users selection.

Don't use a single radio button as once the selection is made the user cannot unselect.