Radio button (web component)

The radio button component is composed of two custom elements: <bolt-radio-group> and <bolt-radio>:

<bolt-radio-group label="Group label goes here" name="controlName" >
    <bolt-radio value="1">Item 1 label</bolt-radio>
    <bolt-radio value="2">Item 2 label</bolt-radio>
    <bolt-radio value="3">Item 3 label</bolt-radio>
</bolt-radio-group>

<bolt-radio-group label="Group label 2 goes here" name="contro2lName" horizontal>
    <bolt-radio value="1">Yes</bolt-radio>
    <bolt-radio value="2">No</bolt-radio>
</bolt-radio-group>

The <bolt-radio-group> element provides a wrapper around native <fieldset> and <legend> elements, applying a label (via the label attribute) to the set of <bolt-radio> elements.

The two elements must be used together. Only <bolt-radio> elements can be children of the <bolt-radio-group>.

The <bolt-radio-group> element must include one of these three parameters:

• label: The label text, used to populate the underlying <legend> element.
• arialabel: If present, sets the aria-label attribute of the underlying <fieldset> element.
• arialabelledby: If present, sets the aria-labelledby attribute of the underlying <fieldset> element.

Additionally, the <bolt-radio-group> element supports the following parameters:

• name: required. The value for the name attribute must be unique for each set of options.
• horizontal: optional. Radio buttons are stacked vertically by default, which should be the case for the majority of uses. If present, this causes the radio buttons to display horizontally. Please see the "Design guidelines" tab for details on when this option should be used.
• value: optional. The currently selected value.
• instructionaltext: optional. The instructional text to display below the label. This should be used to give users additional information about the radio group.
• required: optional. If present, the field is required. Fields that are not required will show "(optional)".
• optionaltext: optional. show (default) or hide. Use to remove the "(optional)" text from non-required fields.
• disabled: optional. If present, disables rendered interactive elements.
• error: optional. The error message to display.
  • Should not be used when component is disabled.
• invalid: optional. If present, the group appears invalid.
• bounded: optional. If present, the radio buttons appear with a bounded border.
  • Bounded radio buttons do not support contextual help on individual options. See description instead.

The <bolt-radio-group> element supports the use of <bolt-contextual-help> via the help slot placeholder. For more information and to see other options visit the contextual help page.

The <bolt-radio> element provides a wrapper arount native <input> and <label> elements and apply appropriate layout and data access APIs.

<bolt-radio> supports the following attributes:

• value: required. The value of the radio button, which must be a string. The value attribute will not accept an object.
• disabled: optional. If present, disables rendered interactive elements.
• checked: optional. If present, the control is checked. This can be used instead of the bolt-radio-group's value attribute.
• arialabel: optional. If present, sets the aria-label attribute of the underlying <label> element.
• arialabelledby: optional. If present, sets the aria-labelledby attribute of the underlying <label> element.
• invalid: optional. If present, the control appears invalid.
• datatestradio: optional. Property to configure the data-test value on the underlying <input> element.
• description: optional. Property adds descriptive text to an individual radio button. Must be plain text.
  • Can't be used with horizontal layout.

Note The <bolt-radio> slotted content can only contain plain text which sets the visual label for the radio button.

• <bolt-radio>
  • [data-test="radio-N"] targets rendered radio <input>, where N is a zero-based index (e.g., radio-0 for the first rendered radio, radio-1 for the 2nd rendered radio, etc.)
    • Configurable on each <bolt-radio> via the datatestradio property
      • datatestradio property MUST be configured when <bolt-radio> element is added to the DOM

• Radio buttons should be placed in a logical order (e.g., alphabetical, most likely to least likely, simplest to most complex, least to most risk).
• Include an "Other," "Does not apply," or similar option for users who may not want to answer or if not all possible options are listed. Consider alternatives if a selection is not required, like using a Radio group with an option equating to "none of these options."
• Text labels should wrap, keeping the Radio selector glyph itself aligned with the first line of a label.
• Except for decisions that require a boolean choice (e.g., Yes/No, True/False, etc.), do not use side-by-side horizontal positioning of radio buttons to prevent an unintended visual grouping of unrelated options.
• Lay out lists of Radio buttons vertically, with one option per line for ease of comprehension.
• A Radio button should not be used on its own; it should be rendered in a group of at least two or more options.
• Combine Radio buttons with a fieldset and legend for the best context and accessibility.
• Both the Radio button AND its label should be able to be used to make a selection.
• To verify a deliberate selection, no Radio button should be selected by default unless a selection must be made by default for a page to render (example, a defaulted selection in a filter).
• Once a Radio button is selected, it cannot be deselected. Choosing another related Radio button should change the state back to unselected.
• Avoid individual Radio button validation messages or styles; validation should be displayed at the group level.
• Input validation and error messaging for Radio buttons should only occur after form submission.
• Radio buttons may be used in a list, form, or table for single selections.

• When a user must make a single, mutually exclusive selection from 2-8 options.
• When a selection doesn't have an immediate effect and/or requires form submission.
• When viewing all available options is critical.

• Don't use Radio buttons as an alternative to a Button or Link for actions or navigation.

• Avoid using Radio buttons when multiple choices are allowed; use Checkboxes instead.
• Avoid Radio buttons for situations where users can deselect items; use Checkboxes instead.
• Avoid Radio buttons when a selection results in immediate changes, especially on mobile; use Switch instead.
• Avoid Radio buttons when it's visually difficult to observe the state change; use Switch instead.
• If there are more than 8 options presented, use Select in order to avoid clutter.

• Radio button labels use sentence case.
• Error messages use sentence case and include a period.
• Keep labels and legends concise and simple.

• Safari + Voice over will not read descriptive text automatically and instead announce that more content is available.

All Bolt components have gone through accessibility testing, but please keep our accessibility guidelines in mind.