Morningstar Design System

Buttons

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

Buttons

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

    2.31.0

Buttons trigger interactions throughout the experience.

Variations Design Guidelines Code Reference Accessibility

Button

Variations

Primary

Use for highest-priority actions that are required to complete the user’s task.

Primary
Primary
Button Text Button Text
HTML Web Component 
<!-- Default -->
<button class="mds-button mds-button--primary" type="button">
    Button Text
</button>
<!-- Disabled -->
<button class="mds-button mds-button--primary" type="button" disabled>
    Button Text
</button>
<!-- Default -->
<mds-button variation="primary"> Button Text </mds-button>
<!-- Disabled -->
<mds-button variation="primary" disabled> Button Text </mds-button>
  • Use a primary button only once per page.

Secondary

Use for non-critical actions.

Secondary
Secondary
Button Text Button Text
HTML Web Component 
<!-- Default -->
<button class="mds-button mds-button--secondary" type="button">
    Button Text
</button>
<!-- Disabled -->
<button class="mds-button mds-button--secondary" type="button" disabled>
    Button Text
</button>
<!-- Default -->
<mds-button variation="secondary"> Button Text </mds-button>
<!-- Disabled -->
<mds-button variation="secondary" disabled> Button Text </mds-button>
  • Use for most buttons triggering non-critical actions, such as back, cancel, adding or creating an object.

Flat

Use for tertiary actions.

Flat
Flat
Button Text Button Text
HTML Web Component 
<!-- Default -->
<button class="mds-button mds-button--flat" type="button">
    Button Text
</button>
<!-- Disabled -->
<button class="mds-button mds-button--flat" type="button" disabled>
    Button Text
</button>
<!-- Default -->
<mds-button variation="flat"> Button Text </mds-button>
<!-- Disabled -->
<mds-button variation="flat" disabled> Button Text </mds-button>

With Icon

Add Icons to provide additional affordance or meaning to a button.

On Left
On Right
On Left and Right
On Left
Copy Document Copy Document Copy Document
On Right
Continue Continue Continue
On Left and Right
Upload Changes Upload Changes Upload Changes
HTML Web Component 
<button class="mds-button mds-button--primary" type="button">
    <svg class="mds-icon mds-button__icon mds-button__icon--left" aria-hidden="true">
        <use xlink:href="#open-new--s">
        </use>
    </svg>
    <span class="mds-button__text">
        Copy Document
    </span>
</button>
<button class="mds-button mds-button--secondary" type="button">
    <svg class="mds-icon mds-button__icon mds-button__icon--left" aria-hidden="true">
        <use xlink:href="#open-new--s">
        </use>
    </svg>
    <span class="mds-button__text">
        Copy Document
    </span>
</button>
<button class="mds-button mds-button--flat" type="button">
    <svg class="mds-icon mds-button__icon mds-button__icon--left" aria-hidden="true">
        <use xlink:href="#open-new--s">
        </use>
    </svg>
    <span class="mds-button__text">
        Copy Document
    </span>
</button>
<mds-button icon="open-new--s" variation="primary"> Copy Document </mds-button>
<mds-button icon="open-new--s" variation="secondary"> Copy Document </mds-button>
<mds-button icon="open-new--s" variation="flat"> Copy Document </mds-button>
  • Use left icons to emphasize meaning.
  • Use right icons to imply directionality or to indicate a button will open a Menu.

Icon Only

Use for toolbars and displays where words won’t comfortably fit alongside icons.

Icon Only
Icon Only
User User
HTML Web Component 
<!-- Default -->
<button class="mds-button mds-button--icon-only" type="button" aria-label="User">
    <svg class="mds-icon mds-button__icon mds-button__icon--right" aria-hidden="true">
        <use xlink:href="#person-padless">
        </use>
    </svg>
</button>
<!-- Disabled -->
<button class="mds-button mds-button--icon-only mds-button--hover" type="button" disabled>
    <svg class="mds-icon mds-button__icon mds-button__icon--right">
        <use xlink:href="#person-padless">
            <title>User</title>
        </use>
    </svg>
</button>
<!-- Default -->
<mds-button variation="icon-only" icon="person-padless"> User </mds-button>
<!-- Disabled -->
<mds-button variation="icon-only" icon="person-padless" disabled> User </mds-button>
  • Only use when the Icon’s meaning is unambiguous.
  • Consider pairing with a Tooltip to describe the Icon’s underlying action.
Example of a tooltip paired with an icon-only button. Icon-only Button paired with a tooltip.

Button Container

Apply the mds-button__container class to a wrapping parent element to add standard spacing between contained buttons.

Button Container
Button Container
Submit Save
HTML Web Component 
<!-- Primary & Secondary -->
<div class="mds-button__container">
    <button class="mds-button mds-button--primary mds-button--small" type="button">
        Submit
    </button>
    <button class="mds-button mds-button--secondary mds-button--small" type="button">
        Save
    </button>
</div>
<!-- Icon-only Buttons -->
<div class="mds-button__container">
    <button class="mds-button mds-button--icon-only" type="button" aria-label="Notifications">
        <svg class="mds-icon mds-button__icon mds-button__icon--left" aria-hidden="true">
            <use xlink:href="#bell-padless">
            </use>
        </svg>
    </button>
    <button class="mds-button mds-button--icon-only" type="button" aria-label="Create New">
        <svg class="mds-icon mds-button__icon mds-button__icon--left" aria-hidden="true">
            <use xlink:href="#create-padless">
            </use>
        </svg>
    </button>
    <button class="mds-button mds-button--icon-only" type="button" aria-label="Help">
        <svg class="mds-icon mds-button__icon mds-button__icon--left" aria-hidden="true">
            <use xlink:href="#question-circle-padless">
            </use>
        </svg>
    </button>
    <button class="mds-button mds-button--icon-only" type="button" aria-label="My Acccount">
        <svg class="mds-icon mds-button__icon mds-button__icon--left" aria-hidden="true">
            <use xlink:href="#person-padless">
            </use>
        </svg>
    </button>
</div>
<!-- Primary & Secondary -->
<div class="mds-button__container">
    <mds-button variation="primary" size="small"> Submit </mds-button>
    <mds-button variation="secondary" size="small"> Save </mds-button>
</div>
<!-- Icon-only Buttons -->
<div class="mds-button__container">
    <mds-button variation="icon-only" icon="bell-padless" text="Notifications"></mds-button>
    <mds-button variation="icon-only" icon="create-padless" text="New"></mds-button>
    <mds-button variation="icon-only" icon="question-circle-padless" text="Help"></mds-button>
    <mds-button variation="icon-only" icon="person-padless" text="My Account"></mds-button>
</div>

Sizing

Configure button size and icon size independently within the button.

Button Size

Sizing affects text size, icon size, and internal padding. 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
Continue Continue Continue
Medium (Default)
Continue Continue Continue
Large
Continue Continue Continue
Touch
Continue Continue Continue
HTML Web Component 
<button class="mds-button mds-button--small mds-button--primary" type="button">
    <span class="mds-button__text">
        Continue
    </span>
    <svg class="mds-icon mds-button__icon mds-button__icon--right" aria-hidden="true">
        <use xlink:href="#caret-right--s">
        </use>
    </svg>
</button>
<button class="mds-button mds-button--small mds-button--secondary" type="button">
    <span class="mds-button__text">
        Continue
    </span>
    <svg class="mds-icon mds-button__icon mds-button__icon--right" aria-hidden="true">
        <use xlink:href="#caret-right--s">
        </use>
    </svg>
</button>
<button class="mds-button mds-button--small mds-button--flat" type="button">
    <span class="mds-button__text">
        Continue
    </span>
    <svg class="mds-icon mds-button__icon mds-button__icon--right" aria-hidden="true">
        <use xlink:href="#caret-right--s">
        </use>
    </svg>
</button>
<button class="mds-button mds-button--small mds-button--icon-only" type="button">
    <svg class="mds-icon mds-button__icon mds-button__icon--right">
        <use xlink:href="#heart--s">
            <title>Favorite</title>
        </use>
    </svg>
</button>
<mds-button icon-right="caret-right--s" variation="primary" size="small"> Continue </mds-button>
<mds-button icon-right="caret-right--s" variation="secondary" size="small"> Continue </mds-button>
<mds-button icon-right="caret-right--s" variation="flat" size="small"> Continue </mds-button>
<mds-button variation="icon-only" icon="heart--s" text="Favorite" size="small"></mds-button>
  • Never apply mds-button--large or size="large" to an icon-only button.
  • See mixin documentation for additional details on how to create media queries to switch to the touch size.

Icon Size

Icon size is predetermined and applied automatically to with icon and icon-only buttons. To avoid undesirable scaling of icon artwork, use the chart below to choose the correct icon size to use in your button.

Type
Small Button
Medium Button
Large Button
Touch Button

Primary

Small Icon

Small Icon

Default Icon

Default Icon

Secondary

Small Icon

Small Icon

Default Icon

Default Icon

Flat

Small Icon

Small OR Default Icon*

Default Icon

Default Icon

Icon Only

Small Icon

Default Icon

—

Default Icon

* Default size icon may be used within the medium flat button by applying the mds-button--flat-icon-m modifier class to the block level.

Use When

  • Affording interaction to key behaviors and features.
  • Confirming or submitting information entered into a Form.
  • Cancelling an action.
  • Resetting a form or dataset.
  • Closing a container or section.
  • Opening a Menu.
  • Moving forward or backward through a wizard-type workflow.
  • Creating an object within a group.
  • Applying a non-critical action to a dataset.

Don′t Use When

  • Displaying a collection of links to sections. Use Links instead.
  • Linking to an external site. Use Links instead.

Visual Language

Example of paired buttons using the same size.
Do use the same button size for adjacent buttons.
Example of paired buttons incorrectly using different sizes.
Don‘t display normal and small buttons together in the same row.
Example of the primary button being placed to the right in a group of buttons.
Do place primary buttons to the right within a group of buttons.
Example of a primary button incorrectly placed to the left within a group of buttons.
Don‘t place primary buttons to the left within a group of buttons.
Example of the right icon being used to imply a button will open a menu.
Do use left icons to emphasize meaning and right icons to imply directionality or to indicate a button will open a Menu.
Example of a button incorrectly using a non-direction icon on its right side.
Don‘t use left icons to imply directionality or to indicate a button will open a Menu. Don‘t use right icons to emphasize meaning.
Example of icon-only buttons being placed left-most in a group of buttons.
Do place all icon-only buttons to the left or right of paired buttons.
Example of icon-only buttons being incorrectly placed in the middle of a group of buttons.
Don‘t place icon-only buttons between paired buttons.

Editorial

  • Label a button with a verb, like “Copy”, or verb-phrase, like “Copy Document”.
  • Strive for short button labels that clearly describe an action.
  • Avoid lengthy button labels that risk wrapping, particularly in responsive settings.

CSS

Class References

Class
Applies to
Outcome

mds-button

<button>,
<a>,
<input type="submit"/>, <input type="button"/>, <input type="checkbox"/>, <input type="checkbox"/>, or <input type="radio"/>

Applies base button styles to an element. Always couple with a variant for semantics, though a standalone mds-button will apply the same visual treatments as mds-button paired with mds-button--secondary.

mds-button--primary

mds-button

Shows primary button, to be coupled with mds-button.

mds-button--secondary

mds-button

Shows secondary button, to be coupled with mds-button.

mds-button--flat

mds-button

Shows tertiary button, to be coupled with mds-button.

mds-button--icon-only

mds-button

Applies the icon-only styles to a button element. Specifically, it removes the border strokes and background treatments found on primary and secondary buttons.

mds-button--small

mds-button

Adjusts styling to render a small button.

mds-button--large

mds-button

Adjusts styling to render a large button.

mds-button--touch

mds-button

Adjusts styling to render a touch button.

mds-button--icon-left

mds-button--icon

Positions an icon to the left of a button label.

mds-button--icon-right

mds-button--icon

Positions an icon to the right of a button label.

mds-button--flat-icon-m

mds-button--icon

Applies default size to the icon in a medium flat button. Never apply this class when using a small icon.

Mixins

Touch Properties

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

@include mds-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-button-touch-properties();
}
  • The mixin includes all CSS properties required to convert any size into the touch variation, including styling to resize the button icon(s), if applicable. However, the mixin doesn’t update the underlying icon file used. To avoid undesirable scaling, DOM manipulation via JavaScript is required to update the button icon(s). This is only an issue when switching from small or medium to touch. Consider using the web component and programmatically updating the size and icon props.
  • 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.

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

ariaDescribedby

String

—

—

A space-separated list of element id whose content describes the intent of the button.

checked

Boolean

Only valid when type is radio or checkbox

false

Sets the checked attribute for checkbox or radio-based buttons. Used commonly on buttons within Button Groups.

disabled

Boolean

—

false

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

href

String

—

—

If provided, overrides type and makes the underlying HTML element a link.

icon

String

One of: [MDS Icon Name]

—

A string containing a valid MDS icon name. If icon and text are both provided the icon will be rendered to the left of the text.

See the iconography page for available icons.

iconRight

String

One of: [MDS Icon Name]

—

A string containing a valid MDS icon name. When passed, this prop will render an icon to the right of the button’s text.

See the iconography page for available icons.

name

String

Required when type is radio or checkbox

—

Sets the name attribute for checkbox or radio-based buttons. Used commonly on buttons within Button Groups.

size

String

One of: small, medium, large, touch

medium

Alters the size of the button.

text

String

Required

—

The text that appears in the button. Can also be passed via the default slot.

When using the icon-only variation, this text will be used as the aria-label.

type

String

One of: button, reset, submit, checkbox, radio

submit

Sets the HTML element for the button.

value

String

Required when type is radio or checkbox

—

Sets the value attribute for checkbox or radio-based buttons. Used commonly on buttons within Button Groups.

variation

String

One of: primary, secondary, flat, icon-only

secondary

Sets the button variation.

Slots

Default Slot

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

Additional Behaviors

Automatic aria-label for Icon-Only Buttons

Buttons using the icon-only variation will automatically use their text content as the element’s aria-label. Icon-only buttons without text prop content will trigger a validation warning and use undefined as their aria-label.

Usage Examples

Setting size and variation via props. Using the default slot for text content:

<mds-button size="large" variation="primary"> Contact Us </mds-button>

Setting variation, icon, and text via props:

<mds-button variation="icon-only" icon="bell" text="Notifications"></mds-button>

Setting variation and icon via props. Using the default slot for text content:

<mds-button variation="secondary" icon="person-plus--s"> Add Client </mds-button>

Setting icon and iconRight via props. Using the default slot for text content:

<mds-button icon="gear--s" icon-right="caret-down--s"> Settings </mds-button>

Implementation Tips

Removing Inline-Block Space

When pairing buttons together, you’ll find that the extra space around inline-block elements makes it difficult to add precise spaces between them. Remove this space by adding font-size: 0; to the button’s parent container.

See Example on Codepen

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.

Best Practices

  • Use a <button> element type when displaying buttons.
  • An <a> element cannot be triggered from a spacebar press, only from an enter or return press.
  • It is expected that a button can be triggered by pressing spacebar, enter, or return.

Implementation

  • Always include a aria-label attribute on the button tag to describe the button’s intent for icon-only buttons. See Iconography accessibility section.