Morningstar Design System

Radio Buttons

Variations Design Guidelines Code Reference Accessibility

Radio Buttons
updated

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

    2.29.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--84685">
    <input id="peer-group--84685" 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--83267">
    <input id="peer-group--83267" 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--90275">
    <input id="peer-group--90275" 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--17881">
    <input id="peer-group--17881" 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>

With Microcopy

Use to provide supporting text content for the radio button’s label.

With Microcopy
With Microcopy
Peer Group
HTML Web Component 
<label class="mds-form__radio-button" for="peer-group--80907">
    <input id="peer-group--80907" 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 class="mds-form__radio-button-microcopy">
                Competitors in the same industry sector and are of similar size
            </span>
        </span>
    </span>
</label>
<mds-radio-button name="mdswc-radio-example-default-un" value="peer-group" microcopy="Competitors in the same industry sector and are of similar size">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-34717-checked">
                <input id="id-34717-checked" name="id-34717" 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-34717">
                <input id="id-34717" name="id-34717" 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-7989-checked">
                <input id="id-7989-checked" name="id-7989" 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-7989">
                <input id="id-7989" name="id-7989" 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
Touch
Small
Radio Button Label Radio Button Label
Medium (Default)
Radio Button Label Radio Button Label
Large
Radio Button Label Radio Button Label
Touch
Radio Button Label Radio Button Label
HTML Web Component 
<label class="mds-form__radio-button mds-form__radio-button--small" for="radio-button-label--74511">
    <input id="radio-button-label--74511" 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>
<label class="mds-form__radio-button mds-form__radio-button--small" for="radio-button-label--9445">
    <input id="radio-button-label--9445" 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 class="mds-form__radio-button-microcopy">
                Microcopy supporting the radio button label
            </span>
        </span>
    </span>
</label>
<mds-radio-button size="small" name="small-radio-button-wc" value="small">Radio Button Label</mds-radio-button>
<mds-radio-button size="small" name="small-radio-button-wc" value="small" microcopy="Microcopy supporting the radio button label">Radio Button Label</mds-radio-button>
  • See mixin documentation for additional details on how to create media queries to switch to the touch size.

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--touch

mds-form__radio-button

Adjusts styling to render a touch 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.

mds-form__radio-button-group--touch

mds-form__radio-button-group

Adjusts styling to render a touch radio button group label.

Mixins

Touch Properties

Use this mixin to create media queries in your product styles to switch radio buttons to their touch variation.

@include mds-radio-button-touch-properties();

For example, switching to the touch variation on screens with a max-width of 500px:

// Your product SCSS
@media screen and (max-width: 500px) {
    @include mds-radio-button-touch-properties();
}
  • The mixin includes all CSS properties required to convert any size into the touch variation.
  • Use a media query that makes the most sense for your product, in addition to max-width, pointer: coarse is another helpful method for targeting touch screen devices.
  • If you don’t want every instance to change, consider using a wrapping class around the media query to target specific elements in your product.
  • When composing complex forms, consider using the @include mds-form-all-touch-properties(); mixin for efficiency.

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.

microcopy

String

—

—

Microcopy for the radio button.

name

String

Required

—

Sets the name attribute on the radio button.

size

String

One of: small, medium, large, touch

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, touch

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 Tips

Sticky Hover State on Touch Screens

On touch screens, :hover states “stick” after tapping an interactive element. To counter this behavior, MDS provides a mixin that resets component hover states to their default styles:

@include mds-sticky-hover-reset();

The mixin uses a media query based on hover: none to target touch screen devices and includes resets for Buttons, Checkboxes, Inputs, List Groups, Radio Buttons, Search Fields, Selects, Switches, and Textareas. You can apply this mixin within your product’s media queries along with other MDS touch styles, for example:

// Your product SCSS
@media screen and (max-width: 500px) {
    @include mds-sticky-hover-reset();
    @include mds-componentName-touch-properties();

    // The rest of your product’s responsive/touch styles...
}

Implementation