11.0.0-canary.76da7876c.0 • Published 5 years ago

@material/icon-button v11.0.0-canary.76da7876c.0

Weekly downloads
50,366
License
MIT
Repository
github
Last release
5 years ago

Icon buttons

Icon buttons allow users to take actions, and make choices, with a single tap.

Note: For buttons with both icons and text, use the mdc-button component. For more information, see the mdc-button docs.

Using icon buttons

Installation

npm install @material/icon-button

Styles

@use "@material/icon-button";

@include icon-button.core-styles;

JavaScript instantiation

The icon 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 for details.

import {MDCRipple} from '@material/ripple';

const iconButtonRipple = new MDCRipple(document.querySelector('.mdc-icon-button'));
iconButtonRipple.unbounded = true;

Note: See Importing the JS component for more information on how to import JavaScript.

Icons

We recommend using Material Icons from Google Fonts:

<head>
  <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
</head>

However, you can also use SVG, Font Awesome, or any other icon library you wish.

Icon button

<button class="mdc-icon-button material-icons">favorite</button>

Note: The MDC Icon Button can be used with both <button> and <a> tags.

Note: IE11 will not center the icon properly if there is a newline or space after the material icon text.

Icon button toggle

The icon button can be used to toggle between an on and off icon.

To style an icon button as an icon button toggle, add both icons as child elements and place the mdc-icon-button__icon--on class on the icon that represents the on element. If the button should be initialized in the "on" state, then add the mdc-icon-button--on class to the parent button.

<button id="add-to-favorites"
   class="mdc-icon-button"
   aria-label="Add to favorites"
   aria-pressed="false">
   <i class="material-icons mdc-icon-button__icon mdc-icon-button__icon--on">favorite</i>
   <i class="material-icons mdc-icon-button__icon">favorite_border</i>
</button>

Then, instantiate an MDCIconButtonToggle on the root element.

import {MDCIconButtonToggle} from '@material/icon-button';
const iconToggle = new MDCIconButtonToggle(document.querySelector('.mdc-icon-button'));

Icon button toggle with SVG

The icon button toggle can be used with SVGs.

<button id="star-this-item"
   class="mdc-icon-button mdc-icon-button--on"
   aria-label="Unstar this item"
   aria-pressed="true">
   <svg class="mdc-icon-button__icon">
     ...
   </svg>
   <svg class="mdc-icon-button__icon mdc-icon-button__icon--on">
     ...
  </svg>
</button>

Icon button toggle with an image

The icon button toggle can be used with img tags.

<button id="star-this-item"
   class="mdc-icon-button mdc-icon-button--on"
   aria-label="Unstar this item"
   aria-pressed="true">
   <img src="" class="mdc-icon-button__icon"/>
   <img src="" class="mdc-icon-button__icon mdc-icon-button__icon--on"/>
</button>

Icon button toggle with toggled aria label

Some designs may call for the aria label to change depending on the icon button state. In this case, specify the data-aria-label-on (aria label in on state) and aria-data-label-off (aria label in off state) attributes, and omit the aria-pressed attribute.

<button id="add-to-favorites"
   class="mdc-icon-button"
   aria-label="Add to favorites"
   data-aria-label-on="Remove from favorites"
   data-aria-label-off="Add to favorites">
   <i class="material-icons mdc-icon-button__icon mdc-icon-button__icon--on">favorite</i>
   <i class="material-icons mdc-icon-button__icon">favorite_border</i>
</button>

API

CSS classes

CSS ClassDescription
mdc-icon-buttonMandatory.
mdc-icon-button--onThis class is applied to the root element and is used to indicate if the icon button toggle is in the "on" state.
mdc-icon-button__iconThis class is applied to each icon element for the icon button toggle.
mdc-icon-button__icon--onThis class is applied to a icon element and is used to indicate the toggle button icon that is represents the "on" icon.

Sass mixins

To customize an icon button's color and properties, you can use the following mixins.

MixinDescription
density($density-scale)Sets density scale for icon button. Supported density scales range from -5 to 0, (0 being the default).
size($size)Sets the padding for the icon button based on overall size.
ink-color($color)Sets the font color and the ripple color to the provided color value.
disabled-ink-color($color)Sets the font color to the provided color value for a disabled icon button.
flip-icon-in-rtl()Flips icon only in RTL context.

MDCIconButtonToggle properties and methods

PropertyValue TypeDescription
onBooleanSets the toggle state to the provided isOn value.

Events

Event NameEvent Data StructureDescription
MDCIconButtonToggle:change{"detail": {"isOn": boolean}}Emits when the icon is toggled.

MDCIconButtonToggleAdapter

Method SignatureDescription
addClass(className: string) => voidAdds a class to the root element.
removeClass(className: string) => voidRemoves a class from the root element.
hasClass(className: string) => booleanDetermines whether the root element has the given CSS class name.
setAttr(name: string, value: string) => voidSets the attribute name to value on the root element.
notifyChange(evtData: {isOn: boolean}) => voidBroadcasts a change notification, passing along the evtData to the environment's event handling system. In our vanilla implementation, Custom Events are used for this.

MDCIconButtonToggleFoundation

Method SignatureDescription
handleClick()Event handler triggered on the click event. It will toggle the icon from on/off and update aria attributes.
pwa-test-hpwa-test1pwa-test2sot-incubatormdwrapper@beezydev/icon-buttontest-component-library-stencil@everything-registry/sub-chunk-584svmdsvelterialtest-rsmdcsvelte-arcadiauui-componentsvoyager-componentsjsonresume-theme-material-designmaple-material-vuematerial-react-jsmaterial-imbamaterial-components-webmaterial-toolboxmdc-stencilmde-ultimate@worm425/betsy-web-components@xolvio/plate-ui-commentsangular-8-example-appgesdisc-componentsear-material-iconelectron-test-uiember-cli-mdc-icon-buttonflicktrip-webcomponentsclosure-react-icon-buttondemo-stencil-track-listbw-materialdgiot-dashboardstencil-timerstencil-todo-liststencil-track-listspanidea-matertial-tablesolid-material-componentstransposed-grid@gmvdev/materials@infinitebrahmanuniverse/nolb-_matepug-material-design@lcap-ui/icon-button@leanup/material-core@listo-paye/sdk-ui@openremote/or-input@openremote/or-mwc-components@plonquo/ember-material-components@pitaya-components/card@pitaya-components/icon-button@pitaya-components/slider@pitaya-components/top-bar@pitaya-components/topbar@pmwcs/icon-button@preact-material-components/icon-button@betsybot/betsy-web-components@betazuul/icon-button@bitchin/react-material-web@blackpurl/web-components@aurelia-mdc-web/all@aurelia-mdc-web/icon-button@batchforce/core@authentic/mwc-icon-button@aurelia2-mdc-web/icon-button@arterial/icon-button@cpangular/ng-material-theme@codeadraas/vue3-material@defense-unicorns/unicorn-ui@detachhead/smui-icon-button@dev.mohe/mwc-icon-button-toggle@dgiot/dgiot-dashboard@dgiot/dgiot-dashboard-cdn@element-public/react-footer@element-public/react-icon-button@emuanalytics/flow-rdf@morioh/material@lucasecdb/rmdc@mcwv/icon-button@react-universal-dialogs/android@smui/icon-button@qbcart/eshop-app-shell@material/snackbar@material/dialog@materials-elements/core@materials-elements/site@materials-ui/core@materials-ui/site@material/data-table@material/react-icon-button@rmwc/icon-button@mdc-stencil/icon-button@mhamrah/svelte-material-ui@inovex.de/elements
14.0.0

4 years ago

13.0.0

4 years ago

12.0.0

4 years ago

11.0.0

5 years ago

10.0.0

5 years ago

9.0.0

5 years ago

8.0.0

5 years ago

7.0.0

6 years ago

6.0.0

6 years ago

5.1.0

6 years ago

5.0.0

6 years ago

4.0.0

6 years ago

3.2.0

6 years ago

4.0.0-canary.1

6 years ago

4.0.0-canary.0

6 years ago

4.0.0-alpha.0

6 years ago

3.1.0

6 years ago

3.1.0-alpha.0

6 years ago

3.0.0

7 years ago

3.0.0-alpha.1

7 years ago

3.0.0-alpha.0

7 years ago

2.3.0

7 years ago

2.1.1

7 years ago

2.0.0

7 years ago

1.1.0

7 years ago

1.0.1

7 years ago

1.0.0

7 years ago

1.0.0-1

7 years ago

1.0.0-0

7 years ago

0.44.1

7 years ago

0.44.0

7 years ago

0.43.0

7 years ago

0.42.0

7 years ago

0.41.0

7 years ago

0.40.1

7 years ago

0.40.0

7 years ago

0.39.3

7 years ago

0.39.2

7 years ago

0.39.1

7 years ago

0.39.0

7 years ago

0.39.0-0

7 years ago

0.38.1

7 years ago

0.38.0

7 years ago

0.37.1

7 years ago

0.37.0

8 years ago

0.36.0

8 years ago

0.36.0-0

8 years ago