Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 1,000,000+ packages pre-installed, including @material/button with all npm packages installed. Try it out:

@material/button lists no main file and has no index.js, so it can't be directly required. If this is a mistake, please let us know. It may however contain internal files that you can require manually:

// require("@material/button/[??]")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

@material/button v7.0.0

The Material Components for the web button component

Buttons

Buttons allow users to take actions, and make choices, with a single tap.

There are four types of buttons:

  1. Text button
  2. Outlined button
  3. Contained button
  4. Toggle button

Note: Toggle buttons are implemented using the mdc-icon-button component. For more information, see the mdc-icon-button page.

Example of the four button types

Using buttons

Installation

npm install @material/button

Styles

@use "@material/button";

@include button.core-styles;

JavaScript instantiation

The button will work without JavaScript, but you can enhance it to have a ripple effect by instantiating MDCRipple on the root element. See MDC Ripple for details.

import {MDCRipple} from '@material/ripple';

const buttonRipple = new MDCRipple(document.querySelector('.mdc-button'));

Note: See Importing the JS component for more information on how to import JavaScript.

Making buttons accessible

Material Design spec advises that touch targets should be at least 48 x 48 px. To meet this requirement, add the following to your button:

<div class="mdc-touch-target-wrapper">
  <button class="mdc-button mdc-button--touch">
    <div class="mdc-button__ripple"></div>
    <span class="mdc-button__label">My Accessible Button</span>
    <div class="mdc-button__touch"></div>
  </button>
</div>

Note: The outer mdc-touch-target-wrapper element is only necessary if you want to avoid potentially overlapping touch targets on adjacent elements (due to collapsing margins).

Text button

Text buttons are typically used for less-pronounced actions, including those located in dialogs and cards. In cards, text buttons help maintain an emphasis on card content.

Text button example

Text button example

 <button class="mdc-button">
   <div class="mdc-button__ripple"></div>
   <span class="mdc-button__label">Text Button</span>
</button>

Text button with icon example

Text button with bookmark icon example

<button class="mdc-button">
  <div class="mdc-button__ripple"></div>
  <i class="material-icons mdc-button__icon" aria-hidden="true"
    >bookmark</i
  >
  <span class="mdc-button__label">Text Button plus icon</span>
</button>

Outlined button

Outlined buttons are medium-emphasis buttons. They contain actions that are important, but aren’t the primary action in an app.

Outlined button example

Outlined button example

<button class="mdc-button mdc-button--outlined">
  <div class="mdc-button__ripple"></div>
  <span class="mdc-button__label">Outlined Button</span>
</button>

Outlined button with icon example

Outlined button with bookmark icon

<button class="mdc-button mdc-button--outlined">
  <div class="mdc-button__ripple"></div>
  <i class="material-icons mdc-button__icon" aria-hidden="true">bookmark</i>
  <span class="mdc-button__label">Outlined Button plus Icon</span>
</button>

Contained button

Contained buttons are high-emphasis, distinguished by their use of elevation and fill. They contain actions that are primary to your app.

Contained button example

Contained button example

<button class="mdc-button--raised">
  <span class="mdc-button__label">Contained Button</span>
</button>

Note: mdc-button--raised is applied for a contained button with elevation, and mdc-button--unelevated is applied for a contained button flush with the surface.

Contained button with icon example

Contained button with a bookmark icon

<button class="mdc-button mdc-button--raised">
  <div class="mdc-button__ripple"></div>
  <i class="material-icons mdc-button__icon" aria-hidden="true"
    >bookmark</i
  >
  <span class="mdc-button__label">Contained Button plus Icon</span>
</button>

Toggle button

Toggle buttons can be used to select from a group of choices.

There are two types of toggle buttons:

toggle button group

MDC Web currently does not support toggle button groups.

Icon

Icons can be used as toggle buttons when they allow selection, or deselection, of a single choice, such as marking an item as a favorite.

For more details, see the mdc-icon-button page.

Other Variants

Icon

We recommend using Material Icons from Google Fonts:

<head>
  <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
</head>

However, you can also use SVG, Font Awesome, or any other icon library you wish.

To add an icon, add an element with the mdc-button__icon class inside the button element and set the attribute aria-hidden="true". The icon is set to 18px to meet legibility requirements.

<button class="mdc-button">
  <div class="mdc-button__ripple"></div>
  <i class="material-icons mdc-button__icon" aria-hidden="true">favorite</i>
  <span class="mdc-button__label">Button</span>
</button>

It's also possible to use an SVG icon:

<button class="mdc-button">
  <div class="mdc-button__ripple"></div>
  <svg class="mdc-button__icon" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewBox="...">
  ...
  </svg>
  <span class="mdc-button__label">Button</span>
</button>

Trailing Icon

Certain icons make more sense to appear after the button's text label rather than before. This can be accomplished by putting the icon markup after the mdc-button__label element.

<button class="mdc-button">
  <div class="mdc-button__ripple"></div>
  <span class="mdc-button__label">Button</span>
  <i class="material-icons mdc-button__icon" aria-hidden="true">favorite</i>
</button>

Note: The mdc-button__label element is required in order for the trailing icon to be styled appropriately.

Disabled

To disable a button, add the disabled attribute directly to the <button>, or set the disabled attribute on the <fieldset> containing the button. Disabled buttons cannot be interacted with and have no visual interaction effect.

<button class="mdc-button" disabled>
  <div class="mdc-button__ripple"></div>
  <span class="mdc-button__label">Button</span>
</button>

Button theming example

The following example shows text, contained, and outlined button types with Material Theming.

Button theming with three buttons - text, contained, and outlined - with Shrine theming.

Theming with Sass variables

Before importing any MDC Web modules, set the theme colors in your Sass file:

@use "@material/theme" with (
  $primary: #FEDBD0,
  $on-primary: #442C2E
);

In this case we also want to customize the label color of the text and outlined buttons, to fulfill color contrast requirements. Assuming that you've applied the custom-text-button and custom-outlined-button classes to your buttons:

@use "@material/button";

@include button.core-styles;

.custom-text-button,
.custom-outlined-button {
  @include button.ink-color(#84565E);
}

Theming with CSS custom properties

If you want to customize the theme for buttons without changing the theme across the app, you can also use CSS custom properties:

@use "@material/button";

@include button.core-styles;

.custom-text-button,
.custom-outlined-button {
  --mdc-theme-primary: #FEDBD0;
  --mdc-theme-on-primary: #442C2E;

  @include button.ink-color(#84565E);
}

For a more information on theming in general, see this page.

API

CSS classes

CSS ClassDescription
mdc-buttonMandatory. Defaults to a text button that is flush with the surface.
mdc-button__rippleMandatory. Indicates the element which shows the ripple styling.
mdc-button--raisedOptional. Styles a contained button that is elevated above the surface.
mdc-button--unelevatedOptional. Styles a contained button that is flush with the surface.
mdc-button--outlinedOptional. Styles an outlined button that is flush with the surface.
mdc-button__labelRecommended.* Indicates the element containing the button's text label.
mdc-button__iconOptional. Indicates the element containing the button's icon.

Note: The mdc-button__label element is required for buttons with a trailing icon, but it is currently optional for buttons with no icon or a leading icon. In the latter cases, it is acceptable for the text label to simply exist directly within the mdc-button element.
However, the mdc-button__label class may become mandatory for all cases in the future so we recommended to always include it.

Sass mixins

To customize a button's color and properties, you can use the following mixins.

Basic Sass mixins

MDC Button uses MDC Theme's primary color by default. Use the following mixins to customize it.

MixinDescription
filled-accessible($container-fill-color)Sets the container fill color for a contained (raised or unelevated) button, and updates the button's ink, icon, and ripple colors to meet accessibility standards

Advanced Sass mixins

These mixins will override the color of the container, ink, outline or ripple. It is up to you to ensure your button meets accessibility standards.

MixinDescription
container-fill-color($color)Sets the container fill color to the given color for an enabled button.
disabled-container-fill-color($color)Sets the container fill color to the given color for a disabled button.
icon-color($color)Sets the icon color to the given color for an enabled button.
disabled-icon-color($color)Sets the icon color to the given color for a disabled button.
ink-color($color)Sets the ink color to the given color for an enabled button, and sets the icon color to the given color unless icon-color is also used.
disabled-ink-color($color)Sets the ink color to the given color for a disabled button, and sets the icon color to the given color unless icon-color is also used.
density($density-scale)Sets density scale for button. Supported density scale values (-3, -2, -1, 0).
height($height)Sets custom height for button.
shape-radius($radius, $density-scale, $rtl-reflexive)Sets rounded shape to button with given radius size. $density-scale is only required when $radius value is in percentage unit, defaults to $density-default-scale. Set $rtl-reflexive to true to flip radius values in RTL context, defaults to false.
horizontal-padding($padding)Sets horizontal padding to the given number.
outline-color($color)Sets the outline color to the given color for an enabled button.
disabled-outline-color($color)Sets the outline color to the given color for a disabled button.
outline-width($width, $padding)Sets the outline width to the given number (defaults to 2px) and adjusts padding accordingly. $padding is only required in cases where $horizontal-padding is also included with a custom value.

Metadata

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free