Morningstar Design System

Selects

Variations Design Guidelines Code Reference Accessibility

Selects
updated

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

    2.11.0

Selects afford a single selection from a predefined list of options.

See Forms for guidance on composing full forms.

Variations Design Guidelines Code Reference Accessibility

Variations

Default

Use when affording a single selection from a predefined list of options.

Default
Default
HTML Web Component 
<div class="mds-form__select">
    <select class="mds-form__select-input">
        <option class="mds-form__select-option" value="">Select an Expense Type</option>
        <option class="mds-form__select-option" value="vacation">Vacation</option>
        <option class="mds-form__select-option" value="public_college">Public College</option>
        <option class="mds-form__select-option" value="private_college">Private College</option>
        <option class="mds-form__select-option" value="medical">Medical</option>
    </select>
    <div class="mds-form__select-visual-wrap"></div>
    <span class="mds-form__select-open-indicator">
        <svg class="mds-icon mds-form__select-open-icon" aria-hidden="true">
            <use xlink:href="/icons/mds.svg#caret-down--s">
            </use>
        </svg>
    </span>
</div>
<mds-select id="expense-types-1" placeholder="Select an Expense Type" options='[{"text": "Vacation", "value": "vacation"}, {"text": "Public College", "value": "public_college"}, {"text": "Private College", "value": "private_college"}, {"text": "Medical", "value": "medical"}]'></mds-select>
Disabled
Default
HTML Web Component 
<div class="mds-form__select">
    <select class="mds-form__select-input" disabled>
        <option class="mds-form__select-option" value="">Select an Expense Type</option>
        <option class="mds-form__select-option" value="vacation">Vacation</option>
        <option class="mds-form__select-option" value="public_college">Public College</option>
        <option class="mds-form__select-option" value="private_college">Private College</option>
        <option class="mds-form__select-option" value="medical">Medical</option>
    </select>
    <div class="mds-form__select-visual-wrap"></div>
    <span class="mds-form__select-open-indicator">
        <svg class="mds-icon mds-form__select-open-icon" aria-hidden="true">
            <use xlink:href="/icons/mds.svg#caret-down--s">
            </use>
        </svg>
    </span>
</div>
<mds-select id="expense-types-2" disabled placeholder="Select an Expense Type" options='[{"text": "Vacation", "value": "vacation"}, {"text": "Public College", "value": "public_college"}, {"text": "Private College", "value": "private_college"}, {"text": "Medical", "value": "medical"}]'></mds-select>

Always wrap grouped form elements in a mds-form__field-group container. See the Forms composition section for more guidelines on constructing forms.

<div class="mds-form__field-group">
    <label class="mds-form__label" for="expense-type">Expense Type</label>
    <select class="mds-form__select-input" id="expense-type">
        <option class="mds-form__select-option" value="">Select an Expense Type</option>
        <option class="mds-form__select-option" value="vacation">Vacation</option>
        <option class="mds-form__select-option" value="public_college">Public College</option>
        <option class="mds-form__select-option" value="private_college">Private College</option>
        <option class="mds-form__select-option" value="medical">Medical</option>
    </select>
</div>

Sizing

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

Small
Medium (Default)
Large
Small
Medium (Default)
Large
HTML Web Component 
<div class="mds-form__select mds-form__select--small">
    <select class="mds-form__select-input" id="small-select">
        <option class="mds-form__select-option" value="">Select an option</option>
        <option class="mds-form__select-option" value="option_1">Option 1</option>
        <option class="mds-form__select-option" value="option_2">Option 2</option>
    </select>
    <div class="mds-form__select-visual-wrap"></div>
    <span class="mds-form__select-open-indicator">
        <svg class="mds-icon mds-form__select-open-icon" aria-hidden="true">
            <use xlink:href="/icons/mds.svg#caret-down--s">
            </use>
        </svg>
    </span>
</div>
<mds-select id="select-size-small" placeholder="Select an option" size="small" options='[{"text": "Option 1","value": "option_1"}, {"text": "Option 2","value": "option_2"}]'></mds-select>

Don’t Use When

Behaviors

  • Display a user’s selected option after a choice is made.

Editorial

  • Display either “Select an Option” or no text at all as the default selected option.
  • Start the text with a verb.
  • Don’t end text in a select with a period.
  • Keep option names as brief as possible - aim for under 5 words.
  • Use title case.

CSS

Class References

Class
 Applies to
 Outcome

mds-form__select--small

mds-form__select

Adjusts styling to render a small select.

mds-form__select--large

mds-form__select

Adjusts styling to render a large select.

Web Component

Props

Prop Type Validation Default Description

ariaDescribedby

String

—

—

A space separated list of element id, often microcopy or a field error, whose content contains additional information about the select.

ariaInvalid

Boolean

—

—

Adds aria-invalid attribute`. Use when a select is in an error state.

class

String

—

—

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

disabled

Boolean

—

false

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

id

String

Required

—

The id attribute for the HTML element.

placeholder

String

—

—

Adds an <option> with this text to display by default in the select.

options

Array

—

—

An array to be rendred as <option> elements in the select.

Format as follows:
{text, value, class, disabled}

Both class and disabled can be omitted. To enable optgroup, use children prop.

required

Boolean

—

false

If true, adds the required attribute.

size

String

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

medium

Alters the size of the select.

value

String

—

—

The value of the option selected. Omitting this selects an empty value option. Set the text for this empty value option using the placeholder prop.
  • Use kebab-case when setting props in HTML. For example, ariaDescribedby would be written as aria-describedby.

Usage Examples

Setting options and selected value:

<mds-select id="my-select-1" options='[{"text": "Option 1","value": "option_1"}, {"text": "Option 2","value": "option_2"}, {"text": "Option 3","value": "option_3"}]' value="option_2"></mds-select>

Setting placeholder and options:

<mds-select id="my-select-2" placeholder="Choose..." options='[{"text": "Option 1","value": "option_1"}, {"text": "Option 2","value": "option_2"}, {"text": "Option 3","value": "option_3"}]'></mds-select>

Browser Support

  • This component uses a box-shadow property to create an outline. Internet Explorer and Safari have known issues rendering these outlines when using the browser's zoom functionality. This visual defect doesn't affect the functionality of the component.

Implementation

  • Include an aria-describedby attribute on each select that has an .mds-form__microcopy or an .mds-form__field-error component providing additional information. The value of the aria-describedby attribute must match the id attribute on the .mds-form__microcopy or .mds-form__field-error component.
  • Always pair a Label with a select. Include a for attribute on each label with a value matching the id attribute on the corresponding select.