Morningstar Design System

Radio Buttons

Variations Design Guidelines Code Reference Accessibility

Radio Buttons
updated

  • HTML/CSS Available
  • Web Component Beta
  • Last Updated

    2.14.0

Radio buttons afford a single selection from two or more options.

See Forms for guidance on composing full forms.

Variations Design Guidelines Code Reference Accessibility

Variations

Default

Use to afford a single selection from two or more options.

Unselected, Default
Unselected, Hover
Unselected, Focus
Unselected, Default
Peer Group
Unselected, Hover
Peer Group
Unselected, Focus
Peer Group
HTML Web Component 
<label class="mds-form__radio-button" for="peer-group--11694">
    <input id="peer-group--11694" name="html-radio-example-default-un" value="blue" type="radio" class="mds-form__radio-button-input" />
    <span class="mds-form__radio-button-visible-wrap">
        <span class="mds-form__radio-button-visual"></span>
        <span class="mds-form__radio-button-text "> Peer Group </span>
    </span>
</label>
<mds-radio-button name="mdswc-radio-example-default-un">Peer Group</mds-radio-button>
Unselected, Disabled
Unselected, Disabled
Peer Group
HTML Web Component 
<label class="mds-form__radio-button mds-form__radio-button--disabled" for="peer-group--68675">
    <input id="peer-group--68675" name="html-radio-example-disabled-un" value="blue" type="radio" class="mds-form__radio-button-input" disabled />
    <span class="mds-form__radio-button-visible-wrap">
        <span class="mds-form__radio-button-visual"></span>
        <span class="mds-form__radio-button-text "> Peer Group </span>
    </span>
</label>
<mds-radio-button name="mdswc-radio-example-disabled-un" disabled>Peer Group</mds-radio-button>
Selected, Default
Selected, Hover
Selected, Active
Selected, Focus
Selected, Default
Peer Group
Selected, Hover
Peer Group
Selected, Active
Peer Group
Selected, Focus
Peer Group
HTML Web Component 
<label class="mds-form__radio-button" for="choose-this-one--58212">
    <input id="choose-this-one--58212" name="html-radio-example-default" value="blue" type="radio" class="mds-form__radio-button-input" checked />
    <span class="mds-form__radio-button-visible-wrap">
        <span class="mds-form__radio-button-visual"></span>
        <span class="mds-form__radio-button-text "> Choose this one </span>
    </span>
</label>
<mds-radio-button name="mdswc-radio-example-default" checked>Peer Group</mds-radio-button>
Selected, Disabled
Selected, Disabled
Peer Group
HTML Web Component 
<label class="mds-form__radio-button mds-form__radio-button--disabled" for="peer-group--90173">
    <input id="peer-group--90173" name="html-radio-example-disabled" value="blue" type="radio" class="mds-form__radio-button-input" checked disabled />
    <span class="mds-form__radio-button-visible-wrap">
        <span class="mds-form__radio-button-visual"></span>
        <span class="mds-form__radio-button-text "> Peer Group </span>
    </span>
</label>
<mds-radio-button name="mdswc-radio-example-disabled" disabled checked>Peer Group</mds-radio-button>

Radio Group

Stacked
Rank Within
Stacked
Your List Peer Group
HTML Web Component 
<form class="mds-form mds-form--medium-layout" method="post" action="form/processor">
    <div class="mds-form__field-group">
        <fieldset class="mds-form__radio-button-group" role="radiogroup">
            <legend class="mds-form__radio-button-group-label"> Rank Within </legend>
            <label class="mds-form__radio-button" for="id-58557-checked">
                <input id="id-58557-checked" name="id-58557" value="blue" type="radio" class="mds-form__radio-button-input" checked />
                <span class="mds-form__radio-button-visible-wrap">
                    <span class="mds-form__radio-button-visual"></span>
                    <span class="mds-form__radio-button-text "> Your List </span>
                </span>
            </label>
            <label class="mds-form__radio-button" for="id-58557">
                <input id="id-58557" name="id-58557" value="blue" type="radio" class="mds-form__radio-button-input" />
                <span class="mds-form__radio-button-visible-wrap">
                    <span class="mds-form__radio-button-visual"></span>
                    <span class="mds-form__radio-button-text "> Peer Group </span>
                </span>
            </label>
        </fieldset>
    </div>
</form>
<form class="mds-form mds-form--medium-layout" method="post" action="form/processor">
    <div class="mds-form__field-group">
        <mds-radio-button-group label="Rank Within">
            <mds-radio-button checked name="stacked-mdswc" id="stacked-mdswc-1">Your List</mds-radio-button>
            <mds-radio-button name="stacked-mdswc" id="stacked-mdswc-2">Peer Group</mds-radio-button>
        </mds-radio-button-group>
    </div>
</form>
Horizontal
Rank Within
Horizontal
Your List Peer Group
HTML Web Component 
<form class="mds-form mds-form--medium-layout" method="post" action="form/processor">
    <div class="mds-form__field-group mds-form__field-group--horizontal">
        <fieldset class="mds-form__radio-button-group" role="radiogroup">
            <legend class="mds-form__radio-button-group-label"> Rank Within </legend>
            <label class="mds-form__radio-button" for="id-82133-checked">
                <input id="id-82133-checked" name="id-82133" value="blue" type="radio" class="mds-form__radio-button-input" checked />
                <span class="mds-form__radio-button-visible-wrap">
                    <span class="mds-form__radio-button-visual"></span>
                    <span class="mds-form__radio-button-text "> Your List </span>
                </span>
            </label>
            <label class="mds-form__radio-button" for="id-82133">
                <input id="id-82133" name="id-82133" value="blue" type="radio" class="mds-form__radio-button-input" />
                <span class="mds-form__radio-button-visible-wrap">
                    <span class="mds-form__radio-button-visual"></span>
                    <span class="mds-form__radio-button-text "> Peer Group </span>
                </span>
            </label>
        </fieldset>
    </div>
</form>
<form class="mds-form mds-form--medium-layout" method="post" action="form/processor">
    <div class="mds-form__field-group mds-form__field-group--horizontal">
        <mds-radio-button-group label="Rank Within">
            <mds-radio-button checked name="horizontal-mdswc" id="horizontal-mdswc-1">Your List</mds-radio-button>
            <mds-radio-button name="horizontal-mdswc" id="horizontal-mdswc-2">Peer Group</mds-radio-button>
        </mds-radio-button-group>
    </div>
</form>

Sizing

Sizing affects radio button size and text size. The default size is medium, and you can use modifier classes or props to make the radio button smaller or larger.

Small
Medium (Default)
Large
Small
Radio Button Label
Medium (Default)
Radio Button Label
Large
Radio Button Label
HTML Web Component 
<label class="mds-form__radio-button mds-form__radio-button--small" for="small-radio-button">
    <input id="small-radio-button" name="group-name" value="blue" type="radio" class="mds-form__radio-button-input" />
    <span class="mds-form__radio-button-visible-wrap">
        <span class="mds-form__radio-button-visual"></span>
        <span class="mds-form__radio-button-text "> Radio Button Label </span>
    </span>
</label>
<mds-radio-button size="small" id="small-radio-button-wc">Radio Button Label</mds-radio-button>

Use When

  • Seeing all available options is critical. If the options are secondary in importance, consider using a Select.

Visual Language

  • When possible, use the stacked variation. Options are harder to differentiate within the horizontal group.
  • Uses the same :hover and :active styles as the primary Button.

Behaviors

  • If selecting no option is a viable choice, include a radio button within the group with an appropriate label, i.e. “None”.
  • Generally, the first option in the radio group should be selected by default. If preselection of an option can result in incorrect assumptions, i.e., “Male” or “Female”, then no option should be selected by default.
  • A radio button’s label is part of the clickable area of the control.

Editorial

  • For the radio group label, use full sentences with punctuation.
  • Try to keep radio button labels brief and start them with verbs.

CSS

  • Add a matching name attribute to each radio button within a group to ensures that a single selection is achieved.

Class References

Class
Applies to
Outcome

mds-form__radio-button--small

mds-form__radio-button

Adjusts styling to render a small radio button.

mds-form__radio-button--large

mds-form__radio-button

Adjusts styling to render a large radio button.

Web Component

Radio buttons are comprised of two separate web components, each with a dedicated API:

  • Radio Button - Renders the radio button component and offers props for all offered configurations.
  • Radio Button Group - Wraps multiple <mds-radio-button> elements to present them as a group.

Radio Button

Props

Prop
Type
Validation
Default
Description

checked

Boolean

—

false

Sets the checked value of the radio button.

class

String

—

—

A space-separated list of class names that will be appended to the default mds-form__radio-button element.

disabled

Boolean

—

false

If true, sets the disabled attribute on the radio button, rendering it non-interactive, and applies disabled styling.

id

String

—

—

The id attribute for the HTML element.

name

String

Required

—

Name for a set of radio buttons.

size

String

Enum: ["small", "medium", "large"]

medium

Alters the size of the radio button.

text

String

Required

—

Label text for the radio button.

value

String

Required

—

Value for the radio button.

Slots

Default Slot

Any text passed in between <mds-radio-button></mds-radio-button> tags will be used as the radio button’s label. This slot can accept plain text, or a combination of text and link where appropriate. If no content is passed in via the slot and the text prop is empty, the radio button label content will be empty.

Usage Examples

Setting size, checked status, name, value, and label text:

<!-- Using Props -->
<mds-radio-button size="small" name="radio-example" value="yes" text="Yes" checked></mds-radio-button>
<mds-radio-button size="small" name="radio-example" value="no" text="No"></mds-radio-button>
<!-- Using Slots -->
<mds-radio-button size="small" name="radio-example" value="yes" checked> Yes </mds-radio-button>
<mds-radio-button size="small" name="radio-example" value="no"> No </mds-radio-button>

Radio Button Group

Props

Prop
Type
Validation
Default
Description

ariaRequiredText

String

—

“Please select an option.”

Sets the radio button group label’s required indicator aria-label and title to provide a user a descriptive message regarding requirements.

class

String

—

—

A space-separated list of class names that will be appended to the default mds-form__radio-button-group element.

content

String

—

—

Radio buttons to display within the group. Can also be passed using the default slot.

id

String

—

—

The id attribute for the HTML element.

label

String

Required

—

Label for the radio button group.

optional

Boolean

—

false

If true, adds the optional indicator to the right of the label with a default text of “(Optional)”.

optionalText

String

—

“(Optional)”

Use to override the default optional indicator text.

required

Boolean

—

false

If true, adds the required field indicator to the right of the label.

size

String

Enum: ["small", "medium", "large"]

medium

Alters the size of the radio button group label.
  • Use kebab-case when setting props in HTML. For example, optionalText would be written as optional-text.

Slots

Default Slot

Pass two or more <mds-radio-button> elements between the <mds-radio-button-group></mds-radio-button-group> to set the content of the radio button group. This slot can be overridden using the content prop.

Usage Examples

Creating a required radio button group:

<!-- Using Props -->
<mds-radio-button-group required label="Choose an option." content='<mds-radio-button text="Yes" name="radio-group-example" value="yes"></mds-radio-button> <mds-radio-button text="No" name="radio-group-example" value="no"></mds-radio-button>'></mds-radio-button-group>
<!-- Using Slots -->
<mds-radio-button-group required label="Choose an option.">
    <mds-radio-button name="radio-group-example" value="yes"> Yes </mds-radio-button>
    <mds-radio-button name="radio-group-example" value="no"> No </mds-radio-button>
</mds-radio-button-group>

Implementation