@material/icon-toggle
Advanced tools
The existing 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.
MDC Icon Toggle provides a Material Design icon toggle button. It is fully accessible, and is designed to work with any icon set.
npm install @material/icon-toggle
<i class="mdc-icon-toggle material-icons" role="button" aria-pressed="false"
aria-label="Add to favorites" tabindex="0"
data-toggle-on='{"label": "Remove from favorites", "content": "favorite"}'
data-toggle-off='{"label": "Add to favorites", "content": "favorite_border"}'>
favorite_border
</i>
Then in JS:
import {MDCIconToggle} from '@material/icon-toggle';
MDCIconToggle.attachTo(document.querySelector('.mdc-icon-toggle'));
Note that you can access MDCIconToggle via CommonJS/AMD using the default property of the
required object, as well as globally via mdc.IconToggle.
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
un-styled content.
In order to use MDC Icon Toggle, you will need to import an icon set.
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 use any icon set you like! See the Font Awesome section below for details.
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.
<span class="mdc-icon-toggle" role="button" aria-pressed="false"
aria-label="Star this item" tabindex="0"
data-icon-inner-selector=".fa"
data-toggle-on='{"cssClass": "fa-star", "label": "Unstar this item"}'
data-toggle-off='{"cssClass": "fa-star-o", "label": "Star this item"}'>
<i class="fa fa-star-o" aria-hidden="true"></i>
</span>
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 aria-hidden
attribute on the icon. This is important to ensure that screen readers produce the correct output
when reading this element.
Note the use of data-toggle-on and 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:
| Property | Description |
|---|---|
label | The value to apply to the element's "aria-label" attribute. |
content | 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. |
cssClass | A css class to apply to the icon element for the given toggle state. The same rules regarding inner icon elements described for content apply here as well. |
<i class="material-icon mdc-icon-toggle mdc-icon-toggle--disabled"
role="button" tabindex="-1" aria-pressed="false" aria-disabled="true"
data-toggle-on='{"content": "favorite"}' data-toggle-off='{"content": "favorite_border"}'></i>
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.querySelector('.mdc-icon-toggle');
const status = document.getElementById('status');
iconEl.addEventListener('MDCIconToggle:change', ({detail}) => {
status.textContent = `Icon Toggle is ${detail.isOn ? 'on' : 'off'}`;
});
When the icon toggle is initialized, the data-toggle-on and 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 refreshToggleData():
iconToggle.refreshToggleData();
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.
MDCIconToggle APISimilar to regular DOM elements, the MDCIconToggle functionality is exposed through accessor
methods.
MDCIconToggle.onBoolean. Returns whether or not the icon toggle is currently toggled on. Setting this property will update the toggle state.
MDCIconToggle.disabledBoolean. Returns whether or not the icon toggle is currently disabled. Setting this property will update the disabled state.
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:
| Method Signature | Description |
|---|---|
addClass(className: string) => void | Adds a class to the root element, or the inner icon element. |
removeClass(className: string) => void | Removes a class from the root element, or the inner icon element. |
registerInteractionHandler(type: string, handler: EventListener) => void | Registers an event handler for an interaction event, such as click or keydown. |
deregisterInteractionHandler(type: string, handler: EventListener) => void | Removes an event handler for an interaction event, such as click or keydown. |
setText(text: string) => void | Sets the text content of the root element, or the inner icon element. |
getTabIndex() => number | Returns the tab index of the root element. |
setTabIndex(tabIndex: number) => void | Sets the tab index of the root element. |
getAttr(name: string) => string | Returns the value of the attribute name on the root element. Can also return null, similar to getAttribute(). |
setAttr(name: string, value: string) => void | Sets the attribute name to value on the root element. |
rmAttr(name: string) => void | Removes the attribute name on the root element. |
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. |
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 addClass, removeClass, and setText apply to the correct
icon element.
Also note that ripples require their own foundation at the component level. Check out our vanilla
implementation in index.js as a starting point.
MDCIconToggleFoundation.refreshToggleData() => voidAs 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() => booleanReturns true if the foundation's state is toggled on, false otherwise.
MDCIconToggleFoundation.toggle(isOn: boolean = !this.isOn()) => voidToggles 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() => booleanReturns true if the foundation's state is disabled, false otherwise.
MDCIconToggleFoundation.setDisabled(isDisabled: boolean) => voidEnables / disables the foundation's state, updating the component via the adapter methods.
MDCIconToggleFoundation.isKeyboardActivated() => booleanReturns true if the foundation is currently activated by a keyboard event, false otherwise.
Useful for the MDCRippleFoundation.isSurfaceActive() adapter method.
| Mixin | Description |
|---|---|
mdc-icon-toggle-ink-color($color) | Sets the ink color of the icon toggle |
FAQs
The Material Components for the web icon toggle component
The npm package @material/icon-toggle receives a total of 1,724 weekly downloads. As such, @material/icon-toggle popularity was classified as popular.
We found that @material/icon-toggle demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 13 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.