Morningstar Design System

Buttons

Variations Design Guidelines Code Reference Accessibility

Buttons
updated

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

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

Default
Hover
Active
Focus
Default
Button Text
Hover
Button Text
Active
Button Text
Focus
Button Text
HTML Web Component 
<button class="mds-button mds-button--primary"> Button Text </button>
<mds-button variation="primary">Button Text</mds-button>
Disabled
Disabled
Button Text
HTML Web Component 
<button class="mds-button mds-button--primary" disabled> Button Text </button>
<mds-button variation="primary" disabled>Button Text</mds-button>
  • Use a primary button only once per page, though an additional primary button can appear within Modals, Popovers, or Notifications when needed to signal critical actions.

Secondary

Use for non-critical actions.

Default
Hover
Active
Focus
Default
Button Text
Hover
Button Text
Active
Button Text
Focus
Button Text
HTML Web Component 
<button class="mds-button mds-button--secondary"> Button Text </button>
<mds-button variation="secondary">Button Text</mds-button>
Disabled
Disabled
Button Text
HTML Web Component 
<button class="mds-button mds-button--secondary" disabled> Button Text </button>
<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.

Default
Hover
Focus
Default
Button Text
Hover
Button Text
Focus
Button Text
HTML Web Component 
<button class="mds-button mds-button--flat"> Button Text </button>
<mds-button variation="flat">Button Text</mds-button>
Disabled
Disabled
Button Text
HTML Web Component 
<button class="mds-button mds-button--flat" disabled> Button Text </button>
<mds-button variation="flat" disabled>Button Text</mds-button>

With Icon

Add Icons to provide additional affordance 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">
    <svg class="mds-icon mds-button__icon mds-button__icon--left" aria-hidden="true">
        <use xlink:href="/icons/mds.svg#open-new--s">
        </use>
    </svg>
    <span class="mds-button__text"> Copy Document </span>
</button>
<button class="mds-button mds-button--secondary">
    <svg class="mds-icon mds-button__icon mds-button__icon--left" aria-hidden="true">
        <use xlink:href="/icons/mds.svg#open-new--s">
        </use>
    </svg>
    <span class="mds-button__text"> Copy Document </span>
</button>
<button class="mds-button mds-button--flat">
    <svg class="mds-icon mds-button__icon mds-button__icon--left" aria-hidden="true">
        <use xlink:href="/icons/mds.svg#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>
  • Only place an Icon to the left of a button's label to emphasize meaning.
  • Only place an Icon to the right of a button's label to trigger a Menu or imply directionality.

Icon Only

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

Default
Hover
Focus
Default
Hover
Focus
HTML Web Component 
<button class="mds-button mds-button--icon-only" aria-label="User">
    <svg class="mds-icon mds-button__icon mds-button__icon--right" aria-hidden="true">
        <use xlink:href="/icons/mds.svg#person-padless">
        </use>
    </svg>
</button>
<mds-button icon="person-padless" icon-title="User"></mds-button>
Disabled
Disabled
HTML Web Component 
<button class="mds-button mds-button--icon-only mds-button--hover" disabled>
    <svg class="mds-icon mds-button__icon mds-button__icon--right">
        <use xlink:href="/icons/mds.svg#person-padless">
            <title>User</title>
        </use>
    </svg>
</button>
<mds-button icon="person-padless" icon-title="User" disabled></mds-button>
  • Consider pairing with a Tooltip to describe the Icon’s underlying action.
Icon-only Button paired with a tooltip.
  • When pairing with a button, use an $mds-space-inline-left-2-x space and vertically align middle the icon-only button.
  • When pairing with a small button, use the small icon-only button.
Icon-only Button alignment paired with a button.
Do place all icon-only buttons to the left or right of paired buttons.
Do place all icon-only buttons to the left or right of paired buttons.
Don‘t place icon-only buttons between paired buttons.
Don‘t place icon-only buttons between paired buttons.

Sizing

Configure button size and icon size independently within the button.

Button Size

Each button variation allows for small, medium, and large sizes. 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
Continue Continue Continue
Medium (Default)
Continue Continue Continue
Large
Continue Continue Continue
HTML Web Component 
<button class="mds-button mds-button--small mds-button--primary">
    <span class="mds-button__text"> Continue </span>
    <svg class="mds-icon mds-button__icon mds-button__icon--right" aria-hidden="true">
        <use xlink:href="/icons/mds.svg#caret-right--s">
        </use>
    </svg>
</button>
<button class="mds-button mds-button--small mds-button--secondary">
    <span class="mds-button__text"> Continue </span>
    <svg class="mds-icon mds-button__icon mds-button__icon--right" aria-hidden="true">
        <use xlink:href="/icons/mds.svg#caret-right--s">
        </use>
    </svg>
</button>
<button class="mds-button mds-button--small mds-button--flat">
    <span class="mds-button__text"> Continue </span>
    <svg class="mds-icon mds-button__icon mds-button__icon--right" aria-hidden="true">
        <use xlink:href="/icons/mds.svg#caret-right--s">
        </use>
    </svg>
</button>
<button class="mds-button mds-button--small mds-button--icon-only">
    <svg class="mds-icon mds-button__icon mds-button__icon--right">
        <use xlink:href="/icons/mds.svg#heart--s">
            <title>User</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 icon="heart--s" icon-title="User" size="small"></mds-button>
Do use a small button for secondary actions, like creating a rule.
Do use a small button for secondary actions, like creating a rule.
Do use a small button to apply an action to a dataset.
Do use a small button to apply an action to a dataset.
  • Use small buttons in toolbars and Popover and Menu headers.
  • Never apply mds-button--large to an icon-only button.

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

Primary

Small Icon

Small Icon

Default Icon

Secondary

Small Icon

Small Icon

Default Icon

Flat

Small Icon

Small OR Default Icon*

Default Icon

Icon Only

Small 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

Do use the same button size for adjacent buttons.
Do use the same button size for adjacent buttons.
Don‘t display normal and small buttons together in the same row.
Don‘t display normal and small buttons together in the same row.
Do place primary buttons to the right within a group of buttons.
Do place primary buttons to the right within a group of buttons.
Don‘t place primary buttons to the left within a group of buttons.
Don‘t place primary buttons to the left within a group of 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--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.

Web Component

Props

Prop Type Validation Default Description

ariaDescribedby

String

—

—

A space-separated list of element id whose content contains a description of the button’s intent.

checked

Boolean

Conditional based on type = "radio" or type = "checkbox"

false

Sets the checked attribute of the button. Used commonly on buttons within Button Groups.

class

String

—

—

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

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

Enum: [MDS Icon Name]

See the iconography page for icon names.

—

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.

iconRight

String

Enum: [MDS Icon Name List]

See the iconography page for icon names.

—

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

id

String

Conditional based on type = "radio" or type = "checkbox"

—

The id attribute for the HTML element.

name

String

Conditional based on type = "radio" or type = "checkbox"

id if provided

The name attribute for the HTML element.

size

String

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

medium

Alters the size of the button.

text

String

Required

—

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

type

String

Enum: ["button", "reset", "submit", "checkbox", "radio"]

submit

Sets the HTML element for the button.

value

String

Conditional based on type = "radio" or type = "checkbox"

—

The value attribute for checkbox or radio-based buttons.

variation

String

Enum: ["primary", "secondary", "flat", "icon-only"]

primary

Sets the button variation.
  • Use kebab-case when setting props in HTML. For example, iconRight would be written as icon-right.

Slots

Default Slot

Any text or markup passed in between <mds-button></mds-button> tags will be used as the button’s text. This can be overridden with the text prop.

Additional Behaviors

id Requirement

If type is checkbox | radio, you must provide a value for the id prop otherwise the component will trigger a validation warning.

Automatic aria-label Attribute Creation for Icon-Only Buttons

To comply with accessibility guidelines, buttons must have a text prop to provide screen reader accessible text. Button’s using the icon-only variation will automatically use their text content as the element’s aria-label. Icon-only buttons without a text prop will trigger a validation warning.

Usage Examples

Creating a button and modifying its size and variation:

<!-- Using Props -->
<mds-button text="Contact Us" size="large" variation="secondary"></mds-button>
<!-- Using Slots -->
<mds-button size="large" variation="secondary"> Contact Us </mds-button>

Creating an icon-only button with a descriptive title:

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

Creating a button with an icon:

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

Creating a button with a left and right icon:

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

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.