Radio Group

A lightning-radio-group 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-radio-group. 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-radio-group in a Page for name attribute considerations if you want to use the component multiple times in a page.

If the required attribute is specified, at least one radio button 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 specified, radio button selections can't be changed.

This example creates a radio button group with two options and option1 is selected by default. One radio button must be selected as the required attribute is specified.

You can check which values are selected by using the value attribute. To retrieve the values when the selection is changed, use the onchange event handler and call event.detail.value.

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

A radio group that's disabled is always valid. If the radio group is marked required and no option is selected, after you remove focus from the radio group an error message is displayed.

You can override the default message using message-when-value-missing 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. This method returns false if the input is invalid.

For custom error messages, display the message using setCustomValidity() and reportValidity(). For more information, see the lightning-input documentation.

If you're creating a form for Salesforce record data, we recommend using lightning-record-form, lightning-record-edit-form, or lightning-record-view-form. The record form components are automatically wired up to your record data, labels, and field-level help text. For more information, see Work with Records Using Base Components.

To reuse lightning-radio-group 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-radio-group component in a <form> element and provide your own value for name.

If the reused 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.

lightning-radio-group implements the radio button blueprint in the Salesforce Lightning Design System (SLDS).

Set type="button" to create a component that implements the radio button group blueprint in SLDS.

Use the variant attribute with one of these values to change the appearance of the radio group.

• label-hidden hides the radio group label but makes it available to assistive technology. This variant does not hide the option labels.
• label-inline horizontally aligns the label and radio group.
• label-stacked places the label above the radio group.
• standard is the default variant, which displays the radio group label above the options.

To apply additional styling, use the SLDS utility classes with the class attribute.

This example adds a margin around the radio group using an SLDS class.

Component styling hooks use the --slds-c-* prefix and change styling for specific elements or properties of a component. Component-specific styling isn’t recommended, because it’s unsupported for SLDS 2, but existing customizations still work with the original SLDS. If you use component styling hooks, limit the components to SLDS themes until SLDS 2 and the Salesforce Cosmos theme become generally available. See Radio Group: Styling Hooks Overview for documentation on component-specific hooks for this component.

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.