Important - Deprecation Notice
MDCIconToggle component and styles will be removed in a future release. Some of its functionality
will be available in the MDC Icon Button package instead. Bugs and feature requests
will no longer be accepted for the
mdc-icon-toggle package. It is recommended that you migrate to the
mdc-icon-button package to continue to receive new features and updates.
Icon Toggle Buttons
MDC Icon Toggle provides a Material Design icon toggle button. It is fully accessible, and is designed to work with any icon set.
Design & API Documentation
npm install @material/icon-toggle
Then in JS:
Note that you can access
MDCIconToggle via CommonJS/AMD using the
default property of the
required object, as well as globally via
Also note that you may omit the initial
aria-label attribute and
favorite_border content since
they will be added by the component. However, we recommend adding to prevent an initial flash of
In order to use MDC Icon Toggle, you will need to import an icon set.
We recommend using Material Icons from Google Fonts:
However, you can use any icon set you like! See the Font Awesome section below for details.
Using with Font Awesome and similar libraries
Font Awesome and other popular icon font libraries use pseudo-elements in order to
provide the icon, via the
content property. However, MDC Web uses pseudo-elements for ripple styles.
In order to get around this, you can nest the icon itself inside the icon toggle.
data-icon-inner-selector tells MDCIconToggle to look for an element within itself that matches
that selector, and treat it as the element containing the icon. Also note the
attribute on the icon. This is important to ensure that screen readers produce the correct output
when reading this element.
Configuring the icon toggle states
Note the use of
data-toggle-off in the above examples. When an MDCIconToggle
instance is toggled, it looks at this data to determine how to update the element. This is what
allows MDCIconToggle to be so flexible. The
data-toggle-on configuration will be used when the is
MDCIconToggle is toggled on, and vice versa for
data-toggle-off. Both data attributes are encoded
as JSON and can contain the following properties:
||The value to apply to the element's "aria-label" attribute.|
||The text content to set on the element. Note that if an inner icon is used, the text content will be set on that element instead.|
||A css class to apply to the icon element for the given toggle state. The same rules regarding inner icon elements described for
Disabled icon toggles
Listening for change events
MDCIconToggle emits an
MDCIconToggle:change custom event when the value of the icon toggle
changes as a result of user input. This decision was made to align with how
change events work
for normal inputs. In addition, these events do not bubble and cannot be cancelled.
The custom event's
detail object contains a property
isOn denoting whether or not the component
is toggled on.
const iconEl = document;const status = document;iconEl;
Refreshing the toggle data via the vanilla component.
When the icon toggle is initialized, the
data-toggle-off attributes are
cached to prevent redundant JSON parsing whenever the element is interacted with. However, if you
need to, you can call
This simply forwards a call to the foundation's
refreshToggleData() method, causing the
data-toggle-* attributes to be re-parsed and updated.
This method is useful for frameworks that incrementally render DOM. If an icon toggle's data attributes change, the component needs a way to update itself. This is the reason why this method is exposed on the foundation, and simply proxied by the vanilla component.
Similar to regular DOM elements, the
MDCIconToggle functionality is exposed through accessor
Boolean. Returns whether or not the icon toggle is currently toggled on. Setting this property will update the toggle state.
Boolean. Returns whether or not the icon toggle is currently disabled. Setting this property will update the disabled state.
Using the Foundation Class
MDCIconToggle ships with an
MDCIconToggleFoundation class that external frameworks and libraries
can use to build their own MDCIconToggle components with minimal effort. As with all foundation
classes, an adapter object must be provided. The adapter for icon toggles must provide the following
functions, with correct signatures:
||Adds a class to the root element, or the inner icon element.|
||Removes a class from the root element, or the inner icon element.|
||Registers an event handler for an interaction event, such as
||Removes an event handler for an interaction event, such as
||Sets the text content of the root element, or the inner icon element.|
||Returns the tab index of the root element.|
||Sets the tab index of the root element.|
||Returns the value of the attribute
||Sets the attribute
||Removes the attribute
||Broadcasts a change notification, passing along the
Adapter implementer considerations
If you are writing your own adapter, one thing that needs to be considered is the use of
data-icon-inner-selector. This is handled by us at the component level, which means our
foundation is completely unaware of it. To that end, if your framework's Icon Toggle support inner
icon elements, you must ensure that
setText apply to the correct
Also note that ripples require their own foundation at the component level. Check out our vanilla
index.js as a starting point.
Full foundation API
MDCIconToggleFoundation.refreshToggleData() => void
As described above, the
data-toggle-* attributes are cached so as not to have to perform redundant
parsing. If your framework performs incremental rendering, and these attributes change without
re-rendering the component itself, you can call this method to re-parse the data attributes and keep
the foundation updated.
MDCIconToggleFoundation.isOn() => boolean
Returns true if the foundation's state is toggled on, false otherwise.
MDCIconToggleFoundation.toggle(isOn: boolean = !this.isOn()) => void
Toggles the foundation's state, updating the component via the adapter methods. Defaults to the toggling the opposite of the current state if no argument given. If an argument is given, will toggle on if true, off if false.
MDCIconToggleFoundation.isDisabled() => boolean
true if the foundation's state is disabled,
MDCIconToggleFoundation.setDisabled(isDisabled: boolean) => void
Enables / disables the foundation's state, updating the component via the adapter methods.
MDCIconToggleFoundation.isKeyboardActivated() => boolean
true if the foundation is currently activated by a keyboard event,
Useful for the
MDCRippleFoundation.isSurfaceActive() adapter method.
||Sets the ink color of the icon toggle|