| 1 | |
| 2 | title: "Icon buttons"
|
| 3 | layout: detail
|
| 4 | section: components
|
| 5 | excerpt: "Web icon buttons"
|
| 6 | iconId: button
|
| 7 | path: /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 | ```
|
| 21 | npm install @material/icon-button
|
| 22 | ```
|
| 23 |
|
| 24 | ### Styles
|
| 25 |
|
| 26 | ```scss
|
| 27 | @use "@material/icon-button/styles";
|
| 28 | ```
|
| 29 |
|
| 30 | ### JavaScript instantiation
|
| 31 |
|
| 32 | The icon button will work without JavaScript, but you can enhance it to have a ripple effect by instantiating `MDCRipple` on the root element.
|
| 33 | See [MDC Ripple](../mdc-ripple) for details.
|
| 34 |
|
| 35 | ```js
|
| 36 | import {MDCRipple} from '@material/ripple';
|
| 37 |
|
| 38 | const iconButtonRipple = new MDCRipple(document.querySelector('.mdc-icon-button'));
|
| 39 | iconButtonRipple.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 |
|
| 46 | We 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 |
|
| 54 | However, 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 |
|
| 72 | Material Design spec advises that touch targets should be at least 48 x 48 px.
|
| 73 | To 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 |
|
| 87 | The `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 |
|
| 91 | The icon button can be used to toggle between an on and off icon.
|
| 92 |
|
| 93 | To style an icon button as an icon button toggle, add
|
| 94 | both icons as child elements and place the `mdc-icon-button__icon--on` class on the icon that represents the on element.
|
| 95 | If 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 |
|
| 109 | Then, instantiate an `MDCIconButtonToggle` on the root element.
|
| 110 |
|
| 111 | ```js
|
| 112 | import {MDCIconButtonToggle} from '@material/icon-button';
|
| 113 | const iconToggle = new MDCIconButtonToggle(document.querySelector('.mdc-icon-button'));
|
| 114 | ```
|
| 115 |
|
| 116 | ### Icon button toggle with SVG
|
| 117 |
|
| 118 | The 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 |
|
| 138 | The 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 |
|
| 154 | Some designs may call for the aria label to change depending on the icon button
|
| 155 | state. In this case, specify the `data-aria-label-on` (aria label in on state)
|
| 156 | and `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 |
|
| 176 | CSS 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 |
|
| 187 | To customize an icon button's color and properties, you can use the following mixins.
|
| 188 |
|
| 189 | Mixin | 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 |
|
| 199 | Property | Value Type | Description
|
| 200 | --- | --- | ---
|
| 201 | `on` | Boolean | Sets the toggle state to the provided `isOn` value.
|
| 202 |
|
| 203 | ### Events
|
| 204 |
|
| 205 | Event Name | Event Data Structure | Description
|
| 206 | --- | --- | ---
|
| 207 | `MDCIconButtonToggle:change` | `{"detail": {"isOn": boolean}}` | Emits when the icon is toggled.
|
| 208 |
|
| 209 | ### `MDCIconButtonToggleAdapter`
|
| 210 |
|
| 211 | Method 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 |
|
| 221 | Method Signature | Description
|
| 222 | --- | ---
|
| 223 | `handleClick()` | Event handler triggered on the click event. It will toggle the icon from on/off and update aria attributes.
|