Radio Group

A lightning:radioGroup component represents a group of radio buttons that permit only one button to be selected at a time. The component renders radio button <input> elements and assigns the same value to the name attribute for each element. The common name attribute joins the elements in a group. If you select any radio button in that group, any previously selected button in the group is deselected.

In general, we don’t recommend setting the name attribute in lightning:radioGroup. The component automatically generates a unique value for name if none is provided. The generated value ensures a common name for the <input> elements rendered for the radio button group, and is unique in the page.

See Reusing lightning:radioGroup in a Page for name attribute considerations if you want to use the component multiple times in a page.

If the required attribute is true, at least one radio button in the group must be selected. When a user interacts with the radio button group and doesn’t make a selection, an error message is displayed.

If the disabled attribute is true, radio button selections can’t be changed.

This component implements styling from Radio Button in the Lightning Design System. Set type="button" to create a component that implements styling from Radio Button Group in the Lightning Design System.

This example creates a radio group with two options and option1 is selected by default. The name radioButtonGroup is assigned so that only one button can be selected. The required attribute is set so that a user must select one button.

1<aura:component>
2  <aura:attribute
3    name="options"
4    type="List"
5    default="[
6    {'label': 'apples', 'value': 'option1'},
7    {'label': 'oranges', 'value': 'option2'}
8    ]"
9  />
10  <aura:attribute name="value" type="String" default="option1" />
11  <lightning:radioGroup
12    aura:id="mygroup"
13    label="Radio Button Group"
14    options="{! v.options }"
15    value="{! v.value }"
16    onchange="{! c.handleChange }"
17    required="true"
18  />
19</aura:component>

You can check which values are selected by using cmp.find("mygroup").get("v.value"). To retrieve the values when the selection is changed, use the onchange event handler and call event.getParam("value").

1({
2  handleChange: function (cmp, event) {
3    var changeValue = event.getParam("value");
4    alert(changeValue);
5  },
6});

To create radio buttons, pass in the following properties to the options attribute.

Client-side input validation is available for this component. For example, an error message is displayed when the radio group is marked required and no option is selected. Note that a disabled radio group is always valid.

You can override the default message using messageWhenValueMissing when a radio group is required and no option is selected. This message is displayed when you remove focus from the radio group.

To programmatically display error messages on invalid fields, use the reportValidity() method. For custom validity error messages, display the message using setCustomValidity() and reportValidity(). For more information, see the lightning:input documentation.

To reuse lightning:radioGroup in a page or across multiple tabs such as in a Salesforce console app, follow one of these suggestions.

• Omit the name attribute to enable the component to automatically generate a unique name.
• Enclose each lightning:radioGroup component in a <form> element and provide your own value for name.

If the reused the component generates a unique name, each radio button group in the page renders <input> elements grouped correctly so that one value can be selected in each group.

If you provide your own name value and reuse the component with the same name, each radio button group in the page uses the same name value for the <input> elements. The result is that you can select only one value across all radio button groups, instead of one value within a radio button group. If you require your own name value, enclose the reused components in <form> elements to enable the page to use the same name value for multiple radio button groups.

The radio group is nested in a fieldset element that contains a legend element. The legend contains the label value. The fieldset element enables grouping of related radio buttons to facilitate tabbing navigation and speech navigation for accessibility purposes. Similarly, the legend element improves accessibility by enabling a caption to be assigned to the fieldset.