Buttons
Buttons allow users to take actions, and make choices, with a single tap.
Design & API Documentation
Installation
npm install @limetech/mdc-button
Basic Usage
HTML Structure
<button class="mdc-button">
<div class="mdc-button__ripple"></div>
<span class="mdc-button__label">Button</span>
</button>NOTE: Examples here use the generic
<button>, but users can also apply themdc-buttonclass to<a>elements.
Styles
@import "@limetech/mdc-button/mdc-button";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 '@limetech/mdc-ripple';
const buttonRipple = new MDCRipple(document.querySelector('.mdc-button'));See Importing the JS component for more information on how to import JavaScript.
Variants
Contained Button
To style a contained button, add the mdc-button--raised class to the <button> element for a contained button with elevation, or the mdc-button--unelevated class for a contained button flush with the surface.
Outlined Button
To style an outlined button, add the class mdc-button--outlined to the <button> element.
Icons
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 1.125rem 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__labelelement 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>Additional Information
Accessibility
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 that 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).
Style Customization
CSS Classes
| CSS Class | Description |
|---|---|
mdc-button |
Mandatory. Defaults to a text button that is flush with the surface. |
mdc-button__ripple |
Mandatory. Indicates the element which shows the ripple styling. |
mdc-button--raised |
Optional. Styles a contained button that is elevated above the surface. |
mdc-button--unelevated |
Optional. Styles a contained button that is flush with the surface. |
mdc-button--outlined |
Optional. Styles an outlined button that is flush with the surface. |
mdc-button__label |
Recommended.* Indicates the element containing the button's text label. |
mdc-button__icon |
Optional. Indicates the element containing the button's icon. |
*NOTE: The
mdc-button__labelelement 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 themdc-buttonelement. However, themdc-button__labelclass may become mandatory for all cases in the future, so it is recommended to always include it to be future-proof.
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.
| Mixin | Description |
|---|---|
mdc-button-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.
| Mixin | Description |
|---|---|
mdc-button-container-fill-color($color) |
Sets the container fill color to the given color. |
mdc-button-icon-color($color) |
Sets the icon color to the given color. |
mdc-button-ink-color($color) |
Sets the ink color to the given color, and sets the icon color to the given color unless mdc-button-icon-color is also used. |
mdc-button-density($density-scale) |
Sets density scale for button. Supported density scale values (-3, -2, -1, 0). |
mdc-button-height($height) |
Sets custom height of button. |
mdc-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 $mdc-button-density-default-scale. Set $rtl-reflexive to true to flip radius values in RTL context, defaults to false. |
mdc-button-horizontal-padding($padding) |
Sets horizontal padding to the given number. |
mdc-button-outline-color($color) |
Sets the outline color to the given color. |
mdc-button-outline-width($width, $padding) |
Sets the outline width to the given number (defaults to 0.125rem) and adjusts padding accordingly. $padding is only required in cases where mdc-button-horizontal-padding is also included with a custom value. |
Caveat: Edge and CSS Custom Properties
In browsers that fully support CSS custom properties, the above mixins will work if you pass in a MDC Theme property (e.g. primary) as an argument. However, Edge does not fully support CSS custom properties. If you are using the mdc-button-container-fill-color mixin, you must pass in an actual color value for support in Edge.