Radio Group

A lightning-radio-group component represents a group of radio buttons that permit only one button for selection 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 Reuse lightning-radio-group in a Page for name attribute considerations if you want to use the component multiple times in a page.

If you specify the required attribute, 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 appears.

If you specify the disabled attribute, you can’t interact with the radio buttons.

lightning-radio-group implements the radio button blueprint in the Salesforce Lightning Design System (SLDS). The radio button adapts to SLDS 1 or SLDS 2 styling based on the org’s theme or the container app that you use.

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.

1<template>
2    <lightning-radio-group
3        label="Radio Button Group"
4        options={options}
5        value={value}
6        onchange={handleChange}
7        required
8    >
9    </lightning-radio-group>
10</template>

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.

1import { LightningElement } from "lwc";
2export default class MyComponentName extends LightningElement {
3  options = [
4    { label: "Ross", value: "option1" },
5    { label: "Rachel", value: "option2" },
6  ];
7
8  // Select option1 by default
9  value = "option1";
10
11  handleChange(event) {
12    const selectedOption = event.detail.value;
13    console.log("Option selected with value: " + selectedOption);
14  }
15}

To create radio buttons, pass in these 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.

1<form onsubmit={handleSubmit}>
2    <lightning-radio-group name="radioGroup"
3        label="Will you be attending the event?"
4        options={options}
5        value={value}
6        type="radio"
7        lwc:ref="radiogroup"
8        message-when-value-missing="Select an option"
9        required></lightning-radio-group>
10    <lightning-button variant="brand" label="Submit" onclick={handleSubmit} type="submit"></lightning-button>
11</form>

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.

1import { LightningElement } from 'lwc';
2export default class ValidationExample extends LightningElement {
3
4  value = '';
5  get options() {
6    return [
7      { label: 'Yes', value: 'yes' },
8      { label: 'No', value: 'no' },
9    ];
10  }
11
12  handleSubmit(e) {
13    const allValid = this.refs.radiogroup.reportValidity();
14    if (!allValid) {
15      e.preventDefault();
16      this.refs.radiogroup.setCustomValidity("Please select an option");
17      this.refs.radiogroup.showHelpMessageIfInvalid();
18    }
19  }

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.

Use a combination of variants and utility classes to customize the radio group.

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 doesn’t 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.

1<lightning-radio-group
2    label="Radio Group"
3    options={options}
4    value={value}
5    class="slds-m-around_x-small"
6>
7</lightning-radio-group>

Component styling hooks provide CSS custom properties that use the --slds-c-* prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the SLDS 1 component blueprints for available component styling hooks.

For more information, see Style Components Using Lightning Design System Styling Hooks in the Lightning Web Components Developer Guide.

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 assigning a caption to the fieldset.