Radio Group

lightning-radio-group

A radio button group that can have a single option selected.

For Use In

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="radioGroup" model="lwc" namespace="lightning"}

:::::

:::::tab

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.

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.

note: Setting the name attribute in lightning-radio-group isn't recommended. 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 on the page. See Use Multiple Radio Groups on a Page.

Design

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.

Usage

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.

<template>
    <lightning-radio-group
        label="Radio Button Group"
        options={options}
        value={value}
        onchange={handleChange}
        required
    >
    </lightning-radio-group>
</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.

import { LightningElement } from "lwc";
export default class MyComponentName extends LightningElement {
  options = [
    { label: "Ross", value: "option1" },
    { label: "Rachel", value: "option2" },
  ];

  // Select option1 by default
  value = "option1";

  handleChange(event) {
    const selectedOption = event.detail.value;
    console.log("Option selected with value: " + selectedOption);
  }
}

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

Input Validation

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.

<form onsubmit={handleSubmit}>
    <lightning-radio-group name="radioGroup"
        label="Will you be attending the event?"
        options={options}
        value={value}
        type="radio"
        lwc:ref="radiogroup"
        message-when-value-missing="Select an option"
        required></lightning-radio-group>
    <lightning-button variant="brand" label="Submit" onclick={handleSubmit} type="submit"></lightning-button>
</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.

import { LightningElement } from 'lwc';
export default class ValidationExample extends LightningElement {

  value = '';
  get options() {
    return [
      { label: 'Yes', value: 'yes' },
      { label: 'No', value: 'no' },
    ];
  }

  handleSubmit(e) {
    const allValid = this.refs.radiogroup.reportValidity();
    if (!allValid) {
      e.preventDefault();
      this.refs.radiogroup.setCustomValidity("Please select an option");
      this.refs.radiogroup.showHelpMessageIfInvalid();
    }
  }

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.

Use Multiple Radio Groups on a Page

If multiple lightning-radio-group instances on a page or across Salesforce app console tabs share a name attribute, their rendered <input> elements also share the same selection scope. Selecting an option in any single group clears active selections in the remaining groups.

To keep radio group selections independent on the same page or across tabs, choose one of these approaches:

• Omit the name attribute to enable the component to automatically generate a unique name on each instance.
• Enclose each lightning-radio-group component in a <form> element and provide your own value for name. This solution isolates the scope so you can reuse custom name values without causing selection conflicts across radio groups.

Component Styling

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.

Variants

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.

Utility Classes

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.

<lightning-radio-group
    label="Radio Group"
    options={options}
    value={value}
    class="slds-m-around_x-small"
>
</lightning-radio-group>

Styling Hooks

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.

Accessibility

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.

:::::

:::::tab ::component-specification{component="radioGroup" model="lwc" namespace="lightning"}

:::::

::::::