Morningstar Design System

Selects

Variations Design Guidelines Code Reference Accessibility

Selects
updated

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

    2.21.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 
<!-- Default -->
<div class="mds-form__select">
    <select class="mds-form__select-input" id="select-id">
        <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>
<!-- Disabled -->
<div class="mds-form__select">
    <select class="mds-form__select-input" id="select-id" 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>
<!-- Default -->
<mds-select id="select-id" 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 -->
<mds-select id="select-id" 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.

<!-- HTML -->
<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">
        [Options]
    </select>
</div>
<!-- Web Component -->
<mds-field-group>
    <mds-label for="expense-type">Expense Type</mds-label>
    <mds-select id="expense-type" placeholder="Select an Expense Type" options="[Options]"></mds-select>
</mds-field-group>

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="small-select" 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

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__select class.

ariaDescribedby

String

—

—

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

ariaInvalid

String

One of: false, true, grammar, spelling

false

Sets the aria-invalid attribute.

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.

name

String

—

—

The name 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 rendered 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

One of: 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.

Usage Examples

Setting id, options, and value via props:

<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 id, placeholder, and options via props:

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