Morningstar Design System

Selects

Variations Design Guidelines Code Reference Accessibility
You are viewing legacy documentation. View the most recent documentation.

Selects

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

    2.34.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="#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="#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
Touch
Small
Medium (Default)
Large
Touch
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="#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>
  • See mixin documentation for additional details on how to create media queries to switch to the touch size.

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.

mds-form__select--touch

mds-form__select

Adjusts styling to render a touch select.

Mixins

Touch Properties

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

@include mds-select-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-select-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

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

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>

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

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.