Buttons

HTML/CSS Available
Web Component In Progress
Last Updated
2.0.0

Buttons trigger interactions throughout the experience.

Button

Size

S M L

Button Text

Variation

Background Color

That combination of options is invalid.

View Code

Variations

Primary

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

Default

Hover

Active

Focus

White Light Dark Black

<button class="mds-button mds-button--primary" type="button"> Button Text </button>

Disabled

White Light Dark Black

<button class="mds-button mds-button--primary" type="button" disabled> Button Text </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

White Light Dark Black

<button class="mds-button mds-button--secondary" type="button"> Button Text </button>

Disabled

White Light Dark Black

<button class="mds-button mds-button--secondary" type="button" disabled> Button Text </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

White Light Dark Black

<button class="mds-button mds-button--flat" type="button"> Button Text </button>

Disabled

White Light Dark Black

<button class="mds-button mds-button--flat" type="button" disabled> Button Text </button>

With Icon

Add Icons to provide additional affordance to a button.

On Left

On Right

On Left and Right

White Light Dark Black

<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="/icons/mds.svg#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="/icons/mds.svg#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="/icons/mds.svg#open-new--s">
        </use>
    </svg>
    <span class="mds-button__text"> Copy Document </span>
</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

White Light Dark Black

<button class="mds-button mds-button--icon-only" type="button">
    <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>

Disabled

White Light Dark Black

<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="/icons/mds.svg#person-padless">
            <title>User</title>
        </use>
    </svg>
</button>

Only use when the Icon’s meaning is unambiguous.
For toolbars of multiple Icons, use the Button Group component to ensure spacing between icons.
Use with Icon remove or remove--s to close Modals, Notifications, and Tooltip prompts.
Use with Icon remove or remove--s to remove an item from a list.

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.

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

White Light Dark Black

<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="/icons/mds.svg#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="/icons/mds.svg#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="/icons/mds.svg#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="/icons/mds.svg#heart--s">
            <title>User</title>
        </use>
    </svg>
</button>

Do use a small button for secondary actions, like creating a rule.

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.

Guidelines

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.

Don‘t display normal and small buttons together in the same row.

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.

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.

Accessibility

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.
Always include a <title> tag on the svg within an icon-only button to describe the button’s intent for icon-only buttons. See Iconography accessibility section.

Code Reference

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.
`ariaLabel`	String	––	––	A space-separated list of element `id` whose content is a label for the button. Use with icon-only buttons.
`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` is provided and `text` is undefined this will render an icon-only button. If `icon` and `text` are both provided the icon will be rendered to the left of the text.
`iconTitle`	String	––	––	A title describing the icon. Icon-only buttons must include a title to be accessible.
`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.
`iconRightTitle`	String	Conditional based on `iconRight != undefined`	––	A title describing the right icon.
`id`	String	––	––	The `id` attribute for the HTML element.
`name`	String	––	`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	––	––	The text that appears on the button. Can also be passed via the default slot.
`type`	String	Enum: `["button", "reset", "submit", "checkbox", "radio"]`	`button`	Sets the HTML element for the button.
`value`	String	Conditional based on `type = "radio"` or `type = "checkbox"`	none	The `value` attribute for checkbox or radio-based buttons.
`variation`	String	Enum: `["primary", "secondary", "flat"]`	`primary`	Sets the button variation.

Use kebab-case when setting props in HTML. For example, iconRightTitle would be written as icon-right-title.

Slots

Default Slot

Any text or markup passed in between the <mds-button></mds-button> tags will be used as a button's text content.

Named Slots

Slot Name	Description
`icon`	Assigning `slot=”icon”` to an `<mds-icon>` within the `<mds-button></mds-button>` tags will render that element in the icon slot of the button (to the left of the text, if present.)
`icon-right`	Assigning `slot=”icon-right”` to an `<mds-icon>` within the `<mds-button></mds-button>` tags will render that element in the right icon slot of the button.

Additional Behaviors

Automatic ID generation

If type is checkbox | radio and no value is provided for the id prop the component will automatically generate one for you.

Automatic `<title>` Creation for Icon-Only Buttons

To comply with accessibility guidelines icon-only buttons must have a <title> present in the icon’s SVG that provides screen reader accessible text. Use the iconTitle prop to set this text. If an icon only button is invoked without providing an iconTitle the component will automatically use the icon’s name as a title.

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:

<!-- Using Props -->
<mds-button icon="bell" icon-title=”notifications”></mds-button> 

<!-- Using Slots -->
<mds-button> 
    <mds-icon slot=”icon” name=”bell”  title=”notifications></mds-icon> 
</mds-button>

Creating a button with an icon:

<!-- Using Props -->
<mds-button icon=”person-plus--s” text=”Add Client”></mds-button> 

<!-- Using Slots -->
<mds-button>
    <mds-icon slot=”icon” name=”person-plus--s”></mds-icon>
    Add Client  
</mds-button>

Creating a button with a left and right icon:

<!-- Using Props -->
<mds-button icon=”gear--s” text=”Settings” icon-right=”caret-down--s”></mds-button> 

<!-- Using Slots -->
<mds-button>  
    <mds-icon slot=”icon” name=”gear--s”></mds-icon>  
    Settings 
    <mds-icon slot=”icon-right” name=”caret-down--s”></mds-icon> 
</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.

Link Template

Button

Variations

Primary

Secondary

Flat

With Icon

Icon Only

Sizing

Button Size

Icon Size

Guidelines

Use When

Don′t Use When

Visual Language

Editorial

Related UX Patterns

Accessibility

Code Reference

CSS Class References

Web Component

Props

Slots

Default Slot

Named Slots

Additional Behaviors

Automatic ID generation

Automatic <title> Creation for Icon-Only Buttons

Usage Examples

Browser Support

Automatic `<title>` Creation for Icon-Only Buttons