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.

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.

<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>

RadioGroup Props #

The RadioGroup component takes the following React props.

Name	Type	Default	Description
checked	string		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`.
children	React$Node		Mineral Radio components
data			Data used to contruct Radios, see example
defaultChecked	string		Value of the selected Radio; primarily for use with uncontrolled components.
inline	boolean		Display the choices inline horizontally rather than stacked vertically.
name	string	required	The name of the group
onChange			Called when a choice is selected
rootProps	Object		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.

Variable	Value
RadioGroupControl_marginHorizontal_inline	theme.space_inline_xl
RadioGroupControl_marginVertical_stacked	theme.space_stack_md
RadioGroupControl_marginVertical_stackedJumbo	theme.space_stack_lg

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.

Examples #

Import Syntax #

Note

Data vs. Children #

Uncontrolled #

Controlled #

Inline #

FormField #

API & Theme #

RadioGroup Props #

Note

RadioGroup Theme Variables #

Usage #

When/How to Use #

Best Practices #