Radio

Radio allows users to select one option from a set.

Basic Usage

To implement the Radio component, you need to import it first:

import { Radio } from '@react-ui-org/react-ui';

And use it:

React.createElement(() => {
  const [fruit, setFruit] = React.useState('apple');
  return (
    <Radio
      label="Your favourite fruit"
      onChange={(e) => setFruit(e.target.value)}
      options={[
        {
          label: 'Apple',
          value: 'apple',
        },
        {
          label: 'Banana',
          value: 'banana',
        },
        {
          label: 'Grapefruit',
          value: 'grapefruit',
        },
      ]}
      value={fruit}
    />
  );
})

See API for all available options.

General Guidelines

Use Radio for just a few options. For larger sets of many options (say 4 and more) consider using the SelectField component. This will help keep your UI clean and uncluttered and prevent your users from being overwhelmed by too many options.
Don't use for boolean (true/false) selection or to toggle things on and off. CheckboxField and Toggle are more suitable for such cases.
Use short and descriptive labels, ideally nouns rather than seemingly polite phrases like Please select your favourite fruit. Short labels will help your users accomplish their task faster.
Only make the Radio's label invisible when there is another visual clue to guide users through filling the input.
When a short label is not enough, use help texts to guide users before they enter anything.
Use clear, calm error messages when there's a problem with what they entered.
In the background, Radio uses the fieldset element. Not only it improves the accessibility of the group, it also allows you to make use of its built-in features like disabling all nested inputs or pairing the group with a form outside. Consult the MDN docs to learn more.

Invisible Label

While it may be acceptable for login screens with just a few fields or for other simple forms, it's dangerous to hide labels from users in most cases. Keep in mind you should provide another visual clue so users know what to fill into the input.

React.createElement(() => {
  const [frequency, setFrequency] = React.useState('weekly');
  return (
    <Radio
      isLabelVisible={false}
      label="Newsletter frequency"
      onChange={(e) => setFrequency(e.target.value)}
      options={[
        {
          label: 'I want to subscribe to the weekly newsletter',
          value: 'weekly',
        },
        {
          label: 'I want to subscribe to the monthly newsletter',
          value: 'monthly',
        },
        {
          label: "I don't wish to receive anything",
          value: 'never',
        },
      ]}
      value={frequency}
    />
  );
})

Horizontal Layout

The default vertical layout is very easy to use and work with. However, there are situations where horizontal layout suits better — and that's why React UI supports this kind of layout as well.

React.createElement(() => {
  const [frequency, setFrequency] = React.useState('weekly');
  return (
    <Radio
      label="Newsletter frequency"
      layout="horizontal"
      onChange={(e) => setFrequency(e.target.value)}
      options={[
        {
          label: 'I want to subscribe to the weekly newsletter',
          value: 'weekly',
        },
        {
          label: 'I want to subscribe to the monthly newsletter',
          value: 'monthly',
        },
        {
          label: "I don't wish to receive anything",
          value: 'never',
        },
      ]}
      value={frequency}
    />
  );
})

Help Text

You may provide an additional help text to clarify how the input should be filled.

React.createElement(() => {
  const [fruit, setFruit] = React.useState('apple');
  return (
    <Radio
      helpText="What do you prefer?"
      label="Your favourite fruit"
      onChange={(e) => setFruit(e.target.value)}
      options={[
        {
          label: 'Apple',
          value: 'apple',
        },
        {
          label: 'Banana',
          value: 'banana',
        },
        {
          label: 'Grapefruit',
          value: 'grapefruit',
        },
      ]}
      value={fruit}
    />
  );
})

States

Validation States

Validation states visually present the result of validation of the input. You should always provide a validation message for states other than valid so users know what happened and what action they should take or what options they have.

  React.createElement(() => {
    const [fruit, setFruit] = React.useState('apple');
    const options = [
      {
        label: 'Apple',
        value: 'apple',
      },
      {
        label: 'Banana',
        value: 'banana',
      },
      {
        label: 'Grapefruit',
        value: 'grapefruit',
      },
    ];
    return (
      <>
        <Radio
          label="Your favourite fruit"
          onChange={(e) => setFruit(e.target.value)}
          options={options}
          required
          validationState="valid"
          validationText="Great, they're in stock!"
          value={fruit}
        />
        <Radio
          label="Your favourite fruit"
          onChange={(e) => setFruit(e.target.value)}
          options={options}
          required
          validationState="warning"
          validationText="Oh, really?"
          value={fruit}
        />
        <Radio
          label="Your favourite fruit"
          onChange={(e) => setFruit(e.target.value)}
          options={options}
          required
          validationState="invalid"
          validationText="You must select one kind of fruit."
          value={fruit}
        />
      </>
    );
  })

Disabled State

It's possible to disable just some options or the whole set.

  React.createElement(() => {
    const [fruit, setFruit] = React.useState('apple');
    const options = [
      {
        label: 'Apple',
        value: 'apple',
      },
      {
        label: 'Banana',
        value: 'banana',
      },
      {
        disabled: true,
        label: 'Grapefruit',
        value: 'grapefruit',
      },
    ];
    return (
      <>
        <Radio
          label="Your favourite fruit"
          onChange={(e) => setFruit(e.target.value)}
          options={options}
          value={fruit}
        />
        <Radio
          disabled
          label="Your favourite fruit"
          onChange={(e) => setFruit(e.target.value)}
          options={options}
          value="apple"
        />
      </>
    );
  })

Forwarding HTML Attributes

In addition to the options below in the component's API section, you can specify any HTML attribute you like. All attributes that don't interfere with the API of the React component are forwarded to the root <input> HTML element. This enables making the component interactive and helps to improve its accessibility.

👉 For the full list of supported attributes refer to:

API

Theming

Head to Forms Theming to see shared form theming options. On top of that, the following options are available for Radio.

Custom Property	Description
`--rui-FormField--check__input--radio__border-radius`	Input corner radius
`--rui-FormField--check__input--radio--checked__background-image`	Checked input background image (inline, URL, …)