# @material/button > The Material Components for the web button component Latest version **14.0.0** (published 2022-04-28) · MIT license · 0 weekly downloads ## Install ```sh npm install @material/button pnpm add @material/button yarn add @material/button bun add @material/button ``` ## Health **Score 20/100 (F)** — status: abandoned. Positive: no vulnerabilities; popular repo. Warnings: low downloads; no types; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 14.0.0 | | Published | 2022-04-28 | | First published | 2016-12-15 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 13 | | Unpacked size | 625.3 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 17051 | | Maintainers | material-admin, yefim, abhiomkar, azakus, bicknellr, aprigogin, patrickrodee, aomarks, emarquez, allanchen, esgonzalez, asyncliz, candysonya, ssuarez, taylorv | | Keywords | material components, material design, button | ## Links - npm: https://www.npmjs.com/package/@material/button - Repository: https://github.com/material-components/material-components-web - Homepage: https://github.com/material-components/material-components-web#readme - Issues: https://github.com/material-components/material-components-web/issues - npm.io page: https://npm.io/package/@material/button ## Dependencies (13) - [tslib](https://npm.io/package/tslib.md) ^2.1.0 - [@material/dom](https://npm.io/package/@material/dom.md) ^14.0.0 - [@material/rtl](https://npm.io/package/@material/rtl.md) ^14.0.0 - [@material/shape](https://npm.io/package/@material/shape.md) ^14.0.0 - [@material/theme](https://npm.io/package/@material/theme.md) ^14.0.0 - [@material/ripple](https://npm.io/package/@material/ripple.md) ^14.0.0 - [@material/tokens](https://npm.io/package/@material/tokens.md) ^14.0.0 - [@material/density](https://npm.io/package/@material/density.md) ^14.0.0 - [@material/elevation](https://npm.io/package/@material/elevation.md) ^14.0.0 - [@material/focus-ring](https://npm.io/package/@material/focus-ring.md) ^14.0.0 - [@material/typography](https://npm.io/package/@material/typography.md) ^14.0.0 - [@material/touch-target](https://npm.io/package/@material/touch-target.md) ^14.0.0 - [@material/feature-targeting](https://npm.io/package/@material/feature-targeting.md) ^14.0.0 ## Recent versions - 14.0.0 (latest) — 2022-04-28 - 15.0.0-canary.423edc3dc.0 (canary) — 2024-06-26 - 12.0.0-nightly.778a0e8a.0 (nightly) — 2021-07-20 - 4.0.0-alpha.0 (next) — 2019-08-07 - 15.0.0-canary.cfec83c74.0 — 2024-05-20 - 15.0.0-canary.2f5b899bc.0 — 2024-05-20 - 15.0.0-canary.f80ac92b0.0 — 2024-05-02 - 15.0.0-canary.4b35cb7d0.0 — 2024-05-02 - 15.0.0-canary.65c10a622.0 — 2024-04-25 - 15.0.0-canary.311f29a60.0 — 2024-04-23 - 15.0.0-canary.5bebc0064.0 — 2024-04-11 - 15.0.0-canary.68edc03c6.0 — 2024-04-08 - 15.0.0-canary.453a6248a.0 — 2024-03-25 - 15.0.0-canary.819498d8c.0 — 2024-03-15 - 15.0.0-canary.c43b3438b.0 — 2024-02-23 - … 1686 more at https://npm.io/package/@material/button/versions ## README # 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 Text button example ```html ``` Text button with icon example Text button with bookmark 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 Outlined button example ```html ``` Outlined button with icon example Outlined button with bookmark icon ```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 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 Contained button with a bookmark icon ```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) 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](../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. --- _Source: https://npm.io/package/@material/button · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._