1 |
|
2 | title: "Buttons"
|
3 | layout: detail
|
4 | section: components
|
5 | excerpt: "Web Buttons"
|
6 | iconId: button
|
7 | path: /catalog/buttons/
|
8 | -->
|
9 |
|
10 | # Buttons
|
11 |
|
12 | [Buttons](https://material.io/components/buttons/) allow users to take actions, and make choices, with a single tap.
|
13 |
|
14 | There are four types of buttons:
|
15 |
|
16 | 1. [Text button](#text-button)
|
17 | 2. [Outlined button](#outlined-button)
|
18 | 3. [Contained button](#contained-button)
|
19 | 4. [Toggle button](#toggle-button)
|
20 |
|
21 | **Note: Toggle buttons are implemented using the `mdc-icon-button` component.
|
22 | For more information, see the [`mdc-icon-button` page](../mdc-icon-button).**
|
23 |
|
24 | ![Example of the four button types](images/buttons_types.png)
|
25 |
|
26 | ## Using buttons
|
27 |
|
28 | ### Installation
|
29 |
|
30 | ```
|
31 | npm install @material/button
|
32 | ```
|
33 |
|
34 | ### Styles
|
35 |
|
36 | ```scss
|
37 | @use "@material/button/styles";
|
38 | ```
|
39 |
|
40 | ### JavaScript instantiation
|
41 |
|
42 | 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.
|
43 |
|
44 | ```js
|
45 | import {MDCRipple} from '@material/ripple';
|
46 |
|
47 | const buttonRipple = new MDCRipple(document.querySelector('.mdc-button'));
|
48 | ```
|
49 |
|
50 | **Note: See [Importing the JS component](../../docs/importing-js.md) for more information on how to import JavaScript.**
|
51 |
|
52 | ### Making buttons accessible
|
53 |
|
54 | Material Design spec advises that touch targets should be at least 48 x 48 px.
|
55 | To meet this requirement, add the following to your button:
|
56 |
|
57 | ```html
|
58 | <div class="mdc-touch-target-wrapper">
|
59 | <button class="mdc-button mdc-button--touch">
|
60 | <span class="mdc-button__ripple"></span>
|
61 | <span class="mdc-button__touch"></span>
|
62 | <span class="mdc-button__focus-ring"></span>
|
63 | <span class="mdc-button__label">My Accessible Button</span>
|
64 | </button>
|
65 | </div>
|
66 | ```
|
67 | **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).**
|
68 |
|
69 | The `mdc-button__focus-ring` element ensures that a focus indicator is displayed in high contrast mode around the active/focused button.
|
70 |
|
71 | ## Text button
|
72 |
|
73 | [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.
|
74 |
|
75 | ### Text button example
|
76 |
|
77 | <img src="images/text-button.png" alt="Text button example">
|
78 |
|
79 | ```html
|
80 | <button class="mdc-button">
|
81 | <span class="mdc-button__ripple"></span>
|
82 | <span class="mdc-button__focus-ring"></span>
|
83 | <span class="mdc-button__label">Text Button</span>
|
84 | </button>
|
85 | ```
|
86 |
|
87 | <b>Text button with icon example</b>
|
88 |
|
89 | <img src="images/text-icon-button.png" alt="Text button with bookmark icon example">
|
90 |
|
91 | ```html
|
92 | <button class="mdc-button mdc-button--icon-leading">
|
93 | <span class="mdc-button__ripple"></span>
|
94 | <span class="mdc-button__focus-ring"></span>
|
95 | <i class="material-icons mdc-button__icon" aria-hidden="true"
|
96 | >bookmark</i
|
97 | >
|
98 | <span class="mdc-button__label">Text Button plus icon</span>
|
99 | </button>
|
100 |
|
101 | ```
|
102 |
|
103 | ## Outlined button
|
104 |
|
105 | [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.
|
106 |
|
107 | ### Outlined button example
|
108 |
|
109 | <img src="images/outlined-button.png" alt="Outlined button example">
|
110 |
|
111 | ```html
|
112 | <button class="mdc-button mdc-button--outlined">
|
113 | <span class="mdc-button__ripple"></span>
|
114 | <span class="mdc-button__focus-ring"></span>
|
115 | <span class="mdc-button__label">Outlined Button</span>
|
116 | </button>
|
117 | ```
|
118 |
|
119 | <b>Outlined button with icon example</b>
|
120 |
|
121 | <img src="images/outlined-icon-button.png" alt="Outlined button with bookmark icon">
|
122 |
|
123 | ```html
|
124 | <button class="mdc-button mdc-button--outlined mdc-button--icon-leading">
|
125 | <span class="mdc-button__ripple"></span>
|
126 | <span class="mdc-button__focus-ring"></span>
|
127 | <i class="material-icons mdc-button__icon" aria-hidden="true">bookmark</i>
|
128 | <span class="mdc-button__label">Outlined Button plus Icon</span>
|
129 | </button>
|
130 | ```
|
131 |
|
132 | ## Contained button
|
133 |
|
134 | [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.
|
135 |
|
136 | ### Contained button example
|
137 |
|
138 | <img src="images/contained-button.png" alt="Contained button example">
|
139 |
|
140 | ```html
|
141 | <button class="mdc-button mdc-button--raised">
|
142 | <span class="mdc-button__ripple"></span>
|
143 | <span class="mdc-button__focus-ring"></span>
|
144 | <span class="mdc-button__label">Contained Button</span>
|
145 | </button>
|
146 | ```
|
147 |
|
148 | **Note: `mdc-button--raised` is applied for a contained button with elevation,
|
149 | and `mdc-button--unelevated` is applied for a contained button flush with the surface.**
|
150 |
|
151 | <b>Contained button with icon example</b>
|
152 |
|
153 | <img src="images/contained-icon-button.png" alt="Contained button with a bookmark icon">
|
154 |
|
155 | ```html
|
156 | <button class="mdc-button mdc-button--raised mdc-button--icon-leading">
|
157 | <span class="mdc-button__ripple"></span>
|
158 | <span class="mdc-button__focus-ring"></span>
|
159 | <i class="material-icons mdc-button__icon" aria-hidden="true"
|
160 | >bookmark</i
|
161 | >
|
162 | <span class="mdc-button__label">Contained Button plus Icon</span>
|
163 | </button>
|
164 | ```
|
165 |
|
166 | ## Toggle button
|
167 |
|
168 | [Toggle buttons](https://material.io/components/buttons/#toggle-button) can be used to select from a group of choices.
|
169 |
|
170 | There are two types of toggle buttons:
|
171 |
|
172 | * [Toggle button](#toggle-button)
|
173 | * [Icon](#icon)
|
174 |
|
175 | <img src="images/toggle-bar.png" alt="toggle button group">
|
176 |
|
177 | MDC Web currently does not support toggle button groups.
|
178 |
|
179 | ### Icon
|
180 |
|
181 | 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.
|
182 |
|
183 | For more details, see the [`mdc-icon-button` page](../mdc-icon-button).
|
184 |
|
185 | ## Other Variants
|
186 |
|
187 | ### Icon
|
188 |
|
189 | We recommend using [Material Icons](https://material.io/tools/icons/) from Google Fonts:
|
190 |
|
191 | ```html
|
192 | <head>
|
193 | <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
|
194 | </head>
|
195 | ```
|
196 |
|
197 | However, you can also use SVG, [Font Awesome](https://fontawesome.com/), or any other icon library you wish.
|
198 |
|
199 | 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.
|
200 |
|
201 | ```html
|
202 | <button class="mdc-button">
|
203 | <span class="mdc-button__ripple"></span>
|
204 | <span class="mdc-button__focus-ring"></span>
|
205 | <i class="material-icons mdc-button__icon" aria-hidden="true">favorite</i>
|
206 | <span class="mdc-button__label">Button</span>
|
207 | </button>
|
208 | ```
|
209 |
|
210 | It's also possible to use an SVG icon:
|
211 |
|
212 | ```html
|
213 | <button class="mdc-button">
|
214 | <span class="mdc-button__ripple"></span>
|
215 | <span class="mdc-button__focus-ring"></span>
|
216 | <svg class="mdc-button__icon" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewBox="...">
|
217 | ...
|
218 | </svg>
|
219 | <span class="mdc-button__label">Button</span>
|
220 | </button>
|
221 | ```
|
222 |
|
223 | #### Trailing Icon
|
224 |
|
225 | Certain icons make more sense to appear after the button's text label rather than before. This can be accomplished by
|
226 | putting the icon markup _after_ the `mdc-button__label` element.
|
227 |
|
228 | ```html
|
229 | <button class="mdc-button mdc-button--icon-trailing">
|
230 | <span class="mdc-button__ripple"></span>
|
231 | <span class="mdc-button__focus-ring"></span>
|
232 | <span class="mdc-button__label">Button</span>
|
233 | <i class="material-icons mdc-button__icon" aria-hidden="true">favorite</i>
|
234 | </button>
|
235 | ```
|
236 |
|
237 | **Note: The `mdc-button__label` element is _required_ in order for the trailing icon to be styled appropriately.**
|
238 |
|
239 | ### Disabled
|
240 |
|
241 | To disable a button, add the `disabled` attribute directly to the `<button>`, or set the `disabled` attribute on the `<fieldset>` containing the button.
|
242 | Disabled buttons cannot be interacted with and have no visual interaction effect.
|
243 |
|
244 | ```html
|
245 | <button class="mdc-button" disabled>
|
246 | <span class="mdc-button__ripple"></span>
|
247 | <span class="mdc-button__focus-ring"></span>
|
248 | <span class="mdc-button__label">Button</span>
|
249 | </button>
|
250 | ```
|
251 |
|
252 | ## Button theming example
|
253 |
|
254 | The following example shows text, contained, and outlined button types with Material Theming.
|
255 |
|
256 | <img src="images/button-theming.png" width="400" alt="Button theming with three buttons - text, contained, and outlined - with Shrine theming.">
|
257 |
|
258 | ### Theming with Sass variables
|
259 |
|
260 | Before importing any MDC Web modules, set the theme colors in your Sass file:
|
261 |
|
262 | ```scss
|
263 | @use "@material/theme" with (
|
264 | $primary: #FEDBD0,
|
265 | $on-primary: #442C2E
|
266 | );
|
267 | ```
|
268 |
|
269 | In this case we also want to customize the label color of the text and outlined
|
270 | buttons, to fulfill color contrast requirements. Assuming that you've applied
|
271 | the `custom-text-button` and `custom-outlined-button` classes to your buttons:
|
272 |
|
273 | ```scss
|
274 | @use "@material/button";
|
275 |
|
276 | .custom-text-button,
|
277 | .custom-outlined-button {
|
278 | @include button.ink-color(#84565E);
|
279 | }
|
280 | ```
|
281 |
|
282 | ### Theming with CSS custom properties
|
283 |
|
284 | If you want to customize the theme for buttons without changing the theme
|
285 | across the app, you can also use CSS custom properties:
|
286 |
|
287 | ```scss
|
288 | @use "@material/button";
|
289 |
|
290 | .custom-text-button,
|
291 | .custom-outlined-button {
|
292 | --mdc-theme-primary: #FEDBD0;
|
293 | --mdc-theme-on-primary: #442C2E;
|
294 |
|
295 | @include button.ink-color(#84565E);
|
296 | }
|
297 | ```
|
298 |
|
299 | For a more information on theming in general, see
|
300 | [this page](../../docs/theming.md).
|
301 |
|
302 | ## API
|
303 |
|
304 | ### CSS classes
|
305 |
|
306 | CSS Class | Description
|
307 | --- | ---
|
308 | `mdc-button` | Mandatory. Defaults to a text button that is flush with the surface.
|
309 | `mdc-button__ripple` | Mandatory. Indicates the element which shows the ripple styling.
|
310 | `mdc-button--raised` | Optional. Styles a contained button that is elevated above the surface.
|
311 | `mdc-button--unelevated` | Optional. Styles a contained button that is flush with the surface.
|
312 | `mdc-button--outlined` | Optional. Styles an outlined button that is flush with the surface.
|
313 | `mdc-button--icon-leading` | Optional. Styles a button with a leading icon.
|
314 | `mdc-button--icon-trailing` | Optional. Styles a button with a trailing icon.
|
315 | `mdc-button__label` | Recommended.\* Indicates the element containing the button's text label.
|
316 | `mdc-button__icon` | Optional. Indicates the element containing the button's icon.
|
317 | `mdc-button__focus-ring` | Recommended. Indicates the element which shows the high contrast mode focus ring styling.
|
318 |
|
319 | **Note: The `mdc-button__label` element is required for buttons with a trailing icon, but it is currently optional for
|
320 | buttons with no icon or a leading icon. In the latter cases, it is acceptable for the text label to simply exist
|
321 | directly within the `mdc-button` element.<br>
|
322 | However, the `mdc-button__label` class may become mandatory for all cases in the future so we recommend always including it.**
|
323 |
|
324 | ### Sass mixins
|
325 |
|
326 | To customize a button's color and properties, you can use the following mixins.
|
327 |
|
328 | #### Basic Sass mixins
|
329 |
|
330 | MDC Button uses [MDC Theme](../mdc-theme)'s `primary` color by default. Use the following mixins to customize it.
|
331 |
|
332 | Mixin | Description
|
333 | --- | ---
|
334 | `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
|
335 |
|
336 | #### Advanced Sass mixins
|
337 |
|
338 | 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.
|
339 |
|
340 | Mixin | Description
|
341 | --- | ---
|
342 | `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.
|
343 | `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.
|
344 | `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.
|
345 | `density($density-scale)` | Sets density scale for button. Supported density scale values (`-3`, `-2`, `-1`, `0`).
|
346 | `height($height)` | Sets custom height for button.
|
347 | `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.
|
348 | `horizontal-padding($padding)` | Sets horizontal padding to the given number.
|
349 | `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.
|
350 | `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.
|