UNPKG

7.84 kBMarkdownView Raw
1<!--docs:
2title: "Icon buttons"
3layout: detail
4section: components
5excerpt: "Web icon buttons"
6iconId: button
7path: /catalog/buttons/icon-buttons/
8-->
9
10# Icon buttons
11
12[Icon buttons](https://material.io/components/buttons/) allow users to take actions, and make choices, with a single tap.
13
14**Note**: For buttons with both icons and text, use the `mdc-button` component. For more information, see the `mdc-button` [docs](../mdc-button).
15
16## Using icon buttons
17
18### Installation
19
20```
21npm install @material/icon-button
22```
23
24### Styles
25
26```scss
27@use "@material/icon-button/styles";
28```
29
30### JavaScript instantiation
31
32The icon button will work without JavaScript, but you can enhance it to have a ripple effect by instantiating `MDCRipple` on the root element.
33See [MDC Ripple](../mdc-ripple) for details.
34
35```js
36import {MDCRipple} from '@material/ripple';
37
38const iconButtonRipple = new MDCRipple(document.querySelector('.mdc-icon-button'));
39iconButtonRipple.unbounded = true;
40```
41
42**Note**: See [Importing the JS component](../../docs/importing-js.md) for more information on how to import JavaScript.
43
44### Icons
45
46We recommend using [Material Icons](https://material.io/tools/icons/) from Google Fonts:
47
48```html
49<head>
50 <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
51</head>
52```
53
54However, you can also use SVG, [Font Awesome](https://fontawesome.com/), or any other icon library you wish.
55
56## Icon button
57
58```html
59<button class="mdc-icon-button material-icons">
60 <div class="mdc-icon-button__ripple"></div>
61 <span class="mdc-icon-button__focus-ring"></span>
62 favorite
63</button>
64```
65
66**Note**: The MDC Icon Button can be used with both `<button>` and `<a>` tags.
67
68**Note**: IE11 will not center the icon properly if there is a newline or space after the material icon text.
69
70### Making icon buttons accessible
71
72Material Design spec advises that touch targets should be at least 48 x 48 px.
73To meet this requirement, add the following to your button:
74
75```html
76<div class="mdc-touch-target-wrapper">
77 <button class="mdc-icon-button material-icons">
78 <div class="mdc-icon-button__ripple"></div>
79 <span class="mdc-icon-button__focus-ring"></span>
80 favorite
81 <div class="mdc-icon-button__touch"></div>
82 </button>
83</div>
84```
85**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).**
86
87The `mdc-icon-button__focus-ring` element ensures that a focus indicator is displayed in high contrast mode around the active/focused icon button.
88
89## Icon button toggle
90
91The icon button can be used to toggle between an on and off icon.
92
93To style an icon button as an icon button toggle, add
94both icons as child elements and place the `mdc-icon-button__icon--on` class on the icon that represents the on element.
95If the button should be initialized in the "on" state, then add the `mdc-icon-button--on` class to the parent `button`.
96
97```html
98<button id="add-to-favorites"
99 class="mdc-icon-button"
100 aria-label="Add to favorites"
101 aria-pressed="false">
102 <div class="mdc-icon-button__ripple"></div>
103 <span class="mdc-icon-button__focus-ring"></span>
104 <i class="material-icons mdc-icon-button__icon mdc-icon-button__icon--on">favorite</i>
105 <i class="material-icons mdc-icon-button__icon">favorite_border</i>
106</button>
107```
108
109Then, instantiate an `MDCIconButtonToggle` on the root element.
110
111```js
112import {MDCIconButtonToggle} from '@material/icon-button';
113const iconToggle = new MDCIconButtonToggle(document.querySelector('.mdc-icon-button'));
114```
115
116### Icon button toggle with SVG
117
118The icon button toggle can be used with SVGs.
119
120```html
121<button id="star-this-item"
122 class="mdc-icon-button mdc-icon-button--on"
123 aria-label="Unstar this item"
124 aria-pressed="true">
125 <div class="mdc-icon-button__ripple"></div>
126 <span class="mdc-icon-button__focus-ring"></span>
127 <svg class="mdc-icon-button__icon">
128 ...
129 </svg>
130 <svg class="mdc-icon-button__icon mdc-icon-button__icon--on">
131 ...
132 </svg>
133</button>
134```
135
136### Icon button toggle with an image
137
138The icon button toggle can be used with `img` tags.
139
140```html
141<button id="star-this-item"
142 class="mdc-icon-button mdc-icon-button--on"
143 aria-label="Unstar this item"
144 aria-pressed="true">
145 <div class="mdc-icon-button__ripple"></div>
146 <span class="mdc-icon-button__focus-ring"></span>
147 <img src="" class="mdc-icon-button__icon"/>
148 <img src="" class="mdc-icon-button__icon mdc-icon-button__icon--on"/>
149</button>
150```
151
152### Icon button toggle with toggled aria label
153
154Some designs may call for the aria label to change depending on the icon button
155state. In this case, specify the `data-aria-label-on` (aria label in on state)
156and `aria-data-label-off` (aria label in off state) attributes, and omit the
157`aria-pressed` attribute.
158
159```html
160<button id="add-to-favorites"
161 class="mdc-icon-button"
162 aria-label="Add to favorites"
163 data-aria-label-on="Remove from favorites"
164 data-aria-label-off="Add to favorites">
165 <div class="mdc-icon-button__ripple"></div>
166 <span class="mdc-icon-button__focus-ring"></span>
167 <i class="material-icons mdc-icon-button__icon mdc-icon-button__icon--on">favorite</i>
168 <i class="material-icons mdc-icon-button__icon">favorite_border</i>
169</button>
170```
171
172## API
173
174### CSS classes
175
176CSS Class | Description
177--- | ---
178`mdc-icon-button` | Mandatory.
179`mdc-icon-button__ripple` | Mandatory. Indicates the element which shows the ripple styling.
180`mdc-icon-button--on` | This class is applied to the root element and is used to indicate if the icon button toggle is in the "on" state.
181`mdc-icon-button__icon` | This class is applied to each icon element for the icon button toggle.
182`mdc-icon-button__icon--on` | This class is applied to a icon element and is used to indicate the toggle button icon that is represents the "on" icon.
183`mdc-icon-button__focus-ring` | Recommended. Indicates the element which shows the high contrast mode focus ring styling.
184
185### Sass mixins
186
187To customize an icon button's color and properties, you can use the following mixins.
188
189Mixin | Description
190--- | ---
191`density($density-scale)` | Sets density scale for icon button. Supported density scales range from `-5` to `0`, (`0` being the default).
192`size($size)` | Sets the padding for the icon button based on overall size.
193`ink-color($color)` | Sets the font color and the ripple color to the provided color value.
194`disabled-ink-color($color)` | Sets the font color to the provided color value for a disabled icon button.
195`flip-icon-in-rtl()` | Flips icon only in RTL context.
196
197### `MDCIconButtonToggle` properties and methods
198
199Property | Value Type | Description
200--- | --- | ---
201`on` | Boolean | Sets the toggle state to the provided `isOn` value.
202
203### Events
204
205Event Name | Event Data Structure | Description
206--- | --- | ---
207`MDCIconButtonToggle:change` | `{"detail": {"isOn": boolean}}` | Emits when the icon is toggled.
208
209### `MDCIconButtonToggleAdapter`
210
211Method Signature | Description
212--- | ---
213`addClass(className: string) => void` | Adds a class to the root element.
214`removeClass(className: string) => void` | Removes a class from the root element.
215`hasClass(className: string) => boolean` | Determines whether the root element has the given CSS class name.
216`setAttr(name: string, value: string) => void` | Sets the attribute `name` to `value` on the root element.
217`notifyChange(evtData: {isOn: boolean}) => void` | Broadcasts a change notification, passing along the `evtData` to the environment's event handling system. In our vanilla implementation, Custom Events are used for this.
218
219### `MDCIconButtonToggleFoundation`
220
221Method Signature | Description
222--- | ---
223`handleClick()` | Event handler triggered on the click event. It will toggle the icon from on/off and update aria attributes.