# Buttons [Buttons](https://material.io/components/buttons/) allow users to take actions, and make choices, with a single tap. There are four types of buttons: 1. [Text button](#text-button) 2. [Outlined button](#outlined-button) 3. [Contained button](#contained-button) 4. [Toggle button](#toggle-button) **Note: Toggle buttons are implemented using the `mdc-icon-button` component. For more information, see the [`mdc-icon-button` page](../mdc-icon-button).** ![Example of the four button types](images/buttons_types.png) ## Using buttons ### Installation ``` npm install @material/button ``` ### Styles ```scss @use "@material/button/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](../mdc-ripple) for details. ```js import {MDCRipple} from '@material/ripple'; const buttonRipple = new MDCRipple(document.querySelector('.mdc-button')); ``` **Note: See [Importing the JS component](../../docs/importing-js.md) 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: ```html

``` **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).** The `mdc-button__focus-ring` element ensures that a focus indicator is displayed in high contrast mode around the active/focused button. ## Text button [Text buttons](https://material.io/components/buttons/#text-button) 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

```html ``` Text button with icon example

```html ``` ## Outlined button [Outlined buttons](https://material.io/components/buttons/#outlined-button) are medium-emphasis buttons. They contain actions that are important, but aren’t the primary action in an app. ### Outlined button example

```html ``` Outlined button with icon example

```html ``` ## Contained button [Contained buttons](https://material.io/components/buttons/#contained-button) are high-emphasis, distinguished by their use of elevation and fill. They contain actions that are primary to your app. ### Contained button example

```html ``` **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

```html ``` ## Toggle button [Toggle buttons](https://material.io/components/buttons/#toggle-button) can be used to select from a group of choices. There are two types of toggle buttons: * [Toggle button](#toggle-button) * [Icon](#icon)

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](../mdc-icon-button). ## Other Variants ### Icon We recommend using [Material Icons](https://material.io/tools/icons/) from Google Fonts: ```html ``` However, you can also use SVG, [Font Awesome](https://fontawesome.com/), 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. ```html ``` It's also possible to use an SVG icon: ```html ``` #### 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. ```html ``` **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 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: ```scss @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: ```scss @use "@material/button"; .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: ```scss @use "@material/button"; .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](../../docs/theming.md). ## API ### 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--icon-leading` | Optional. Styles a button with a leading icon. `mdc-button--icon-trailing` | Optional. Styles a button with a trailing icon. `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. `mdc-button__focus-ring` | Recommended. Indicates the element which shows the high contrast mode focus ring styling. **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 recommend always including 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](../mdc-theme)'s `primary` color by default. Use the following mixins to customize it. Mixin | Description --- | --- `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 --- | --- `container-fill-color($color-or-map)` | If a color is passed, sets the default container fill color to the given color. If a map is passed whose keys are in the set {default, hover, focus, pressed, disabled}, sets the color in each specified state to its corresponding value. `icon-color($color-or-map)` | If a color is passed, sets the default icon color to the given color. If a map is passed whose keys are in the set {default, hover, focus, pressed, disabled}, sets the color in each specified state to its corresponding value. `ink-color($color-or-map)` | If a color is passed, sets the default ink color to the given color, and sets the icon color to the given color unless `icon-color` is also used. If a map is passed whose keys are in the set {default, hover, focus, pressed, disabled}, sets the color in each specified state to its corresponding value. `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-or-map)` | If a color is passed, sets the default outline color to the given color. If a map is passed whose keys are in the set {default, hover, focus, pressed, disabled}, sets the color in each specified state to its corresponding value. `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.