The m3e-icon-button component is an icon button users interact with to perform a supplementary action.

npm i @m3e/icon-button

This section outlines usage examples and configuration guidance for the components in this package.

There are four icon button appearance variants: filled, tonal, outlined, and standard (default). Use the variant attribute to change the appearance.

<m3e-icon-button variant="filled">
    <m3e-icon name="check"></m3e-icon>
</m3e-icon-button>
<!-- Additional variants omitted for brevity -->

Icon buttons can come in two shapes: rounded (default) or square. Use the shape attribute to control the shape of a button.

<m3e-icon-button variant="filled" shape="square">
    <m3e-icon name="check"></m3e-icon>
</m3e-icon-button>
<!-- Additional variants omitted for brevity -->

There are five size variants which can be used to add or remove emphasis: extra-small, small (default), medium, large, and extra-large. Use the size attribute to control an icon button's size.

<m3e-icon-button variant="tonal" size="extra-small">
    <m3e-icon name="add"></m3e-icon>
</m3e-icon-button>
<!-- Additional sizes omitted for brevity -->

There are three width variants which can be used to add or remove emphasis: default (default), narrow, and wide. Use the width attribute to control an icon button's width.

<m3e-icon-button variant="tonal" width="narrow">
  <m3e-icon name="add"></m3e-icon>
</m3e-icon-button>
<m3e-icon-button variant="tonal" width="wide">
  <m3e-icon name="add"></m3e-icon>
</m3e-icon-button>

Use the toggle attribute to control whether an icon button can be used for binary selection and the selected attribute to control the selected state. When clicked, a cancellable input event is emitted followed by a change event. To cancel selection change, call preventDefault during input.

<m3e-icon-button variant="filled" toggle>
    <m3e-icon name="check"></m3e-icon>
</m3e-icon-button>
<!-- Additional variants omitted for brevity -->

You can also change the icon presented for a selected toggle button using the selected slot.

<m3e-icon-button variant="tonal" toggle>
  <m3e-icon name="close"></m3e-icon>
  <m3e-icon slot="selected" name="check"></m3e-icon>
</m3e-icon-button>

When selected, icon buttons change shape. Rounded buttons become square and square buttons become rounded. The following illustrates the selected states for both rounded and square icon buttons.

Use the disabled attribute to disable an icon button. By default, disabled icon buttons are not focusable with the keyboard. You can use the disabled-interactive attribute to support focusability of disabled controls to increase their discoverability.

<m3e-icon-button variant="filled" disabled>
  <m3e-icon name="check"></m3e-icon>
</m3e-icon-button>
<m3e-icon-button variant="filled" disabled-interactive>
  <m3e-icon name="check"></m3e-icon>
</m3e-icon-button>

Use the type attribute to control the behavior of an icon button. By default, type is button. You can change this to submit or reset to submit or reset a parenting form when clicked. When submitting a form, you can use the name and value attributes to specify a value.

Icon buttons can also behave like links by specifying a URL using the href attribute. You can also specify target, rel and download similar to native anchor tags.

<m3e-icon-button variant="tonal" href="https://www.google.com" target="_blank">
  <m3e-icon name="open_in_new_window"></m3e-icon>
</m3e-icon-button>

By default, icon buttons are given the ARIA role button, indicating they are clickable elements that trigger actions.

Always provide an accessible label via aria-label or aria-labelledby for each icon button.

Slots have aria-hidden="true" to ensure icons are always hidden from assistive technologies.

When disabling using either the disabled or disabled-interactive attribute, aria-disabled="true" is used to convey to assistive technologies that the icon button is disabled. If disabled using disabled-interactive, tabindex is retained to convey that the icon button continues to be interactive.

When href is specified, the ARIA role link is used instead of button to convey the icon button provides an interactive reference to a resource. In addition, the component presents an internal anchor, hidden from assistive technologies, used to invoke native browser features such a context menu options and tooltips.

For toggle icon buttons, aria-pressed is used to convey the selected state, even when disabled.

This package uses JavaScript Modules. To use it directly in a browser without a bundler, use a module script similar to the following.

<script type="module" src="/node_modules/@m3e/icon-button/dist/index.js"></script>

In addition, you must use an import map to include dependencies.

<script type="importmap">
  {
    "imports": {
      "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
      "@m3e/core": "/node_modules/@m3e/core/dist/index.js"
    }
  }
</script>

For production, use index.min.js for faster load times.

This package includes a Custom Elements Manifest (custom-elements.json), which documents the properties, attributes, slots, events and CSS custom properties of each component.

You can explore the API below, or integrate the manifest into your own tooling.