Radio Group

Installation

npm install @nib-components/radio-group

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

import RadioGroup from '@nib-components/radio-group';

Interactive demo

Radio icon style

() => {
  const [rating, setRating] = React.useState(null);
  return (
    <FormControl label="Rate us" id="stars" name="stars" valid={false} validated={false} error="Please provide a rating.">
      <RadioGroup
        onChange={e => setRating(e.target.value)}
        value={rating}
        options={{
          1: '1 star',
          2: '2 stars',
          3: '3 stars',
          4: '4 stars',
          5: '5 stars'
        }}
      />
    </FormControl>
  );
};

Button style

() => {
  const [buttonRating, setButtonRating] = React.useState(null);
  return (
    <FormControl label="Rate us" id="stars2" name="stars2" valid={false} validated={false} error="Please provide a rating.">
      <RadioGroup
        onChange={e => setButtonRating(e.target.value)}
        value={buttonRating}
        options={{
          1: '1 star',
          2: '2 stars',
          3: '3 stars',
          4: '4 stars',
          5: '5 stars'
        }}
        component={RadioButton}
      />
    </FormControl>
  );
};

With subtitles

() => {
  const [rating, setRating] = React.useState(null);
  return (
    <FormControl label="Rate us" id="stars3" name="stars3" valid={false} validated={false} error="Please provide a rating.">
      <RadioGroup
        onChange={e => setRating(e.target.value)}
        value={rating}
        options={{
          1: {
            label: '1 star',
            subtitle: 'Poor'
          },
          2: {
            label: '2 stars',
            subtitle: 'Okay'
          },
          3: {
            label: '3 stars',
            subtitle: 'Good'
          },
          4: {
            label: '4 stars',
            subtitle: 'Great'
          },
          5: {
            label: '5 stars',
            subtitle: 'Excellent'
          }
        }}
      />
    </FormControl>
  );
};

Props

As the <RadioGroup/> is wrapped in a <FormControl/>, all FormControl props such as valid, validated, and disabled will be passed down to this component. This includes the id, name and label which will align with the for attribute on the <label>.

All props passed directly to <RadioGroup/> will be applied to the underlying <input> as attributes.

Options

The options prop accepts both an array and dictionary of items, and within each there are further configuration options.

Object

Simple key:value pairs where key is equal to the option value, and the value of the property is the label:

const options = {
  small: 'Small',
  medium: 'Medium',
  large: 'Large'
};

Or a nested object when supporting subtitles or some disabled options:

const options = {
  small: {
    label: 'Small',
    subtitle: 'Lorem ipsum'
  },
  medium: {
    label: 'Medium',
    subtitle: 'Dolor sit amet'
  },
  large: {
    label: 'Large',
    subtitle: 'Consectetuer elit'
  }
};

In certain situations you may find the need to pass a ReactNode as the label:

const options = {
  one: (
    <Columns space={3} verticalAlign="center">
      <Column width="content">
        <SupportSystemIcon />
      </Column>
      <Column>
        <Copy>Lorem ipsum</Copy>
      </Column>
    </Columns>
  ),
  two: (
    <Columns space={3} verticalAlign="center">
      <Column width="content">
        <ShoppingCartSystemIcon />
      </Column>
      <Column>
        <Copy>Dolor sit amet</Copy>
      </Column>
    </Columns>
  )
};

Array

Using an array guarantees order.

When using an array each item must be an object with a value and label property, and can have a optional subtitle property and an optional disabled property:

const options = [
  {value: 'small', label: 'Small'},
  {value: 'medium', label: 'Medium'},
  {value: 'large', label: 'Large'}
];

Similarly, array options can have subtitles, be individually disabled and can use a ReactNode for the label:

const optionsWithSubtitles = [
  {value: 'small', label: 'Small', subtitle: 'Lorem ipsum'},
  {value: 'medium', label: 'Medium', subtitle: 'Dolor sit amet'},
  {value: 'large', label: 'Large', subtitle: 'Consectetuer elit', disabled: true}
];

const const optionsWithReactNodes = [
  {
    value: 'one',
    label: (
      <Columns space={3} verticalAlign="center">
        <Column width="content">
          <SupportSystemIcon />
        </Column>
        <Column>
          <Copy>Lorem ipsum</Copy>
        </Column>
      </Columns>
    )
  },
  {
    value: 'two',
    label: (
      <Columns space={3} verticalAlign="center">
        <Column width="content">
          <ShoppingCartSystemIcon />
        </Column>
        <Column>
          <Copy>Dolor sit amet</Copy>
        </Column>
      </Columns>
    )
  }
];

Considerations

Radio inputs are used when there are a number of options available and the user may select only one option at any time. Selecting one radio input deselects the others.

Subtitles are optional and should be used to provide more context to the option. Subtitles should be added to all options in the group, or none. Otherwise, alignment will suffer, especially if rendering the options inline.

When a user is able to select multiple options at once use Checkbox.

Order radio options from most likely to least likely to be selected.

When there are 6 or more options consider using a Select.

Related components

• Radio
• Radio Button
• Checkbox
• Form Control