Components

RadioGroup

RadioGroup allows authors to construct a group of Radios and provides a simpler API than working with Radio directly.

RadioGroup allows users to select a single option from a list.

Examples #

Import Syntax #

import { RadioGroup } from 'mineral-ui/Radio';

Note

RadioGroups should be wrapped in a FormField to provide an accessible label and other features. Examples here omit labels for clarity and brevity.

Data vs. Children #

Use either the data prop or children to construct a group of related controls.

<DemoForm>
  <RadioGroup
    name="mineral-1"
    defaultChecked="quartz"
    data={[
      { label: 'Fluorite', value: 'fluorite' },
      { label: 'Magnetite', value: 'magnetite' },
      { label: 'Quartz', value: 'quartz' }
    ]} />

  <FormFieldDivider />

  <RadioGroup name="mineral-2" defaultChecked="pyrite">
    <Radio label="Azurite" value="azurite" />
    <Radio label="Hematite" value="hematite" />
    <Radio label="Pyrite" value="pyrite" />
  </RadioGroup>
</DemoForm>

Uncontrolled #

Create an uncontrolled RadioGroup by using the defaultChecked prop rather than the checked prop.

<DemoForm>
  <RadioGroup
    name="mineral"
    defaultChecked="quartz"
    data={[
      { label: 'Fluorite', value: 'fluorite' },
      { label: 'Magnetite', value: 'magnetite' },
      { label: 'Quartz', value: 'quartz' }
    ]} />
</DemoForm>

Controlled #

Provide the checked prop and an onChange handler to create a controlled component.

() => {
  class MyForm extends Component {
    constructor(props) {
      super(props);

      this.state = {
        value: 'quartz'
      };

      this.handleChange = this.handleChange.bind(this);
    }

    handleChange(event) {
      this.setState({
        value: event.target.value
      });
    }

    render() {
      return (
        <DemoForm>
          <RadioGroup
            name="mineral"
            onChange={this.handleChange}
            checked={this.state.value}
            data={[
              { label: 'Fluorite', value: 'fluorite' },
              { label: 'Magnetite', value: 'magnetite' },
              { label: 'Quartz', value: 'quartz' }
            ]} />
        </DemoForm>
      );
    }
  }

  return <MyForm />;
}

Inline #

Use the inline prop to display choices inline horizontally rather than stacked vertically.

<DemoForm>
  <RadioGroup
    inline
    name="mineral"
    defaultChecked="quartz"
    data={[
      { label: 'Fluorite', value: 'fluorite' },
      { label: 'Magnetite', value: 'magnetite' },
      { label: 'Quartz', value: 'quartz' }
    ]} />
</DemoForm>

FormField #

Use a FormField to provide an accessible label and other features as well as a more streamlined API.

What is your preferred contact method?Required
We promise not to spam you.
<DemoForm>
  <FormField
    input={RadioGroup}
    label="What is your preferred contact method?"
    caption="We promise not to spam you."
    name="contact"
    defaultChecked="none"
    required
    data={[
      { label: 'Email', value: 'email' },
      { label: 'Telephone', value: 'telephone' },
      { label: 'Text message', value: 'text' },
      { label: 'None', value: 'none' }
    ]} />
</DemoForm>

API & Theme #

RadioGroup Props #

The RadioGroup component takes the following React props.

NameTypeDefaultDescription
checkedstring

Value of the selected Radio; primarily for use with controlled components. If this prop is specified, an onChange handler must also be specified. See also: defaultChecked.

childrenReact$Node

Mineral Radio components

data

Data used to contruct Radios, see example

defaultCheckedstring

Value of the selected Radio; primarily for use with uncontrolled components.

inlineboolean

Display the choices inline horizontally rather than stacked vertically.

namestringrequired

The name of the group

onChange

Called when a choice is selected

rootPropsObject

Props to be applied directly to the root element

Note

Unlike most other components, which apply undocumented properties to the root element, RadioGroup applies undocumented properties, including as and css, to the Radio component.

RadioGroup Theme Variables #

These variables can be used as hooks to override this component's style at either a local or global level. The theme referenced below is whatever theme is available from props to the instance of this component.

VariableValue
RadioGroupControl_marginHorizontal_inlinetheme.space_inline_xl
RadioGroupControl_marginVertical_stackedtheme.space_stack_md
RadioGroupControl_marginVertical_stackedJumbotheme.space_stack_lg

Usage #

When/How to Use #

RadioGroup is used to provide a simpler API for creating a group of Radios. It also provides proper row spacing and an inline layout option.

Use a RadioGroup to allow users to select a single option from a list.

Use Radios when the number of choices is fairly small. If the number of choices is large, consider an alternate form control, such as a select, which has a more compact layout.

Use Radios to change settings rather than initiate actions.

Use caution when determining a default selection for a group of Radios.

  • If a default is provided, ensure that it does not make assumptions about your users choices.
  • If a default is not provided, be aware that 'no selection' is a state that users cannot return to once a selection is made.
  • Both of these case can generally be addressed by providing a neutral option. If this is insufficient, consider an alternate form control.

RadioGroups should be wrapped in a FormField to provide an accessible label and other features. See the FormField example for details.

Best Practices #

Use when the number of choices is relatively small.

Contact Method

Use caution when determining a default selection. Don't make assumptions about your users choices.

Contact Method

Use caution when determining a default selection. Provide a neutral option.

Contact Method

Don't use when the user should be able to select multiple options. Use a Checkbox instead.

What do you want in a component library?