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.
<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.
Name | Type | Default | Description |
---|---|---|---|
checked | string | Value of the selected Radio; primarily for use with controlled components. If this prop is specified, an | |
children | React$Node | Mineral Radio components | |
data | |||
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 |
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 |
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.
Use caution when determining a default selection. Don't make assumptions about your users choices.
Use caution when determining a default selection. Provide a neutral option.
Don't use when the user should be able to select multiple options. Use a Checkbox instead.