Morningstar Design System

Radio Buttons

Variations Design Guidelines Code Reference Accessibility

Radio Buttons
updated

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

    2.18.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, Default
Peer Group Peer Group Peer Group Peer Group
HTML Web Component 
<!-- Unselected -->
<label class="mds-form__radio-button" for="peer-group--96066">
    <input id="peer-group--96066" name="html-radio-example-default-un" value="peer-group" 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>
<!-- Unselected, Disabled -->
<label class="mds-form__radio-button mds-form__radio-button--disabled" for="peer-group--89491">
    <input id="peer-group--89491" name="html-radio-example-disabled-un" value="peer-group" 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>
<!-- Selected -->
<label class="mds-form__radio-button" for="peer-group--61932">
    <input id="peer-group--61932" name="html-radio-example-default" value="peer-group" 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 ">
            Peer Group
        </span>
    </span>
</label>
<!-- Selected, Disabled -->
<label class="mds-form__radio-button mds-form__radio-button--disabled" for="peer-group--45810">
    <input id="peer-group--45810" name="html-radio-example-disabled" value="peer-group" 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>
<!-- Unselected -->
<mds-radio-button name="mdswc-radio-example-default-un" value="peer-group">Peer Group</mds-radio-button>
<!-- Unselected, Disabled -->
<mds-radio-button name="mdswc-radio-example-disabled-un" value="peer-group" disabled>Peer Group</mds-radio-button>
<!-- Selected -->
<mds-radio-button name="mdswc-radio-example-default" value="peer-group" checked>Peer Group</mds-radio-button>
<!-- Selected, Disabled -->
<mds-radio-button name="mdswc-radio-example-disabled" value="peer-group" 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-71086-checked">
                <input id="id-71086-checked" name="id-71086" value="your-list" 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-71086">
                <input id="id-71086" name="id-71086" value="peer-group" 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">
    <mds-field-group>
        <mds-radio-button-group label="Rank Within">
            <mds-radio-button checked name="stacked-mdswc" value="your-list">Your List</mds-radio-button>
            <mds-radio-button name="stacked-mdswc" value="peer-group">Peer Group</mds-radio-button>
        </mds-radio-button-group>
    </mds-field-group>
</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-22733-checked">
                <input id="id-22733-checked" name="id-22733" value="your-list" 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-22733">
                <input id="id-22733" name="id-22733" value="peer-group" 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">
    <mds-field-group horizontal>
        <mds-radio-button-group label="Rank Within">
            <mds-radio-button checked name="horizontal-mdswc" value="your-list">Your List</mds-radio-button>
            <mds-radio-button name="horizontal-mdswc" value="peer-group">Peer Group</mds-radio-button>
        </mds-radio-button-group>
    </mds-field-group>
</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="radio-button-label--17979">
    <input id="radio-button-label--17979" name="small-radio-button" value="small" 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" name="small-radio-button-wc" value="small">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.

mds-form__radio-button-group--small

mds-form__radio-button-group

Adjusts styling to render a small radio button group label.

mds-form__radio-button-group--large

mds-form__radio-button-group

Adjusts styling to render a large radio button group label.

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

When setting props as attributes on a custom HTML element, use kebab-case instead of camelCase.

Prop
Type
Validation
Default
Description

additionalClass

String

—

—

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

checked

Boolean

—

false

Sets the checked value of the radio button.

disabled

Boolean

—

false

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

name

String

Required

—

Sets the name attribute on the radio button.

size

String

One of: small, medium, large

medium

Alters the size of the radio button.

text

String

Required

—

The label text for the radio button. Can also be passed via the default slot.

value

String

—

—

Sets the value attribute on the radio button.

Slots

Default Slot

Pass text in between the <mds-radio-button></mds-radio-button> tags to set the radio button’s label text. This can be overridden with the text prop.

Usage Examples

Setting size, checked, name and value via props. Using the default slot for text content:

<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

When setting props as attributes on a custom HTML element, use kebab-case instead of camelCase.

Prop
Type
Validation
Default
Description

additionalClass

String

—

—

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

ariaDescribedby

String

—

—

A space-separated list of element id, often Microcopy or a Field Error, whose content contains additional information about the radio button group.

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.

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

One of: small, medium, large

medium

Alters the size of the radio button group label.

Slots

Default Slot

Pass two or more <mds-radio-button> elements between the <mds-radio-button-group></mds-radio-button-group> tags to set the content of the radio button group.

Usage Examples

Setting required and label via props. Using the default slot for the radio buttons in the group:

<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