The m3e-button component is a semantic, expressive UI primitive users interact with to perform an action.

npm i @m3e/button

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

There are five button appearance variants: elevated, filled, tonal, outlined, and text (default). Use the variant attribute to change the appearance.

<m3e-button variant="elevated">Elevated</m3e-button>
<!-- Additional variants omitted for brevity -->

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

<m3e-button variant="elevated" shape="square">Square Elevated</m3e-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 a button's size.

<m3e-button variant="tonal" size="extra-small">Extra Small</m3e-button>
<!-- Additional sizes omitted for brevity -->

Use the icon slot to render an icon before the button's label. In addition, use the trailing-icon slot to render an icon after the button's label. While not required, the following example uses the m3e-icon component from @m3e/icon to present icons using Material Symbols.

<m3e-button variant="tonal">
  <m3e-icon slot="icon" name="send"></m3e-icon>Send
</m3e-button>
<m3e-button variant="tonal">
  Open<m3e-icon slot="trailing-icon" name="open_in_new_window"></m3e-icon>
</m3e-button>

Use the toggle attribute to control whether a 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-button variant="elevated" toggle>Elevated Toggle</m3e-button>
<!-- Additional variants omitted for brevity -->

In addition, you can use the selected and selected-icon slots to specify an alternate label and icon when selected. When using the m3e-icon to present icons, the icon will automatically be filled when a button is selected.

<m3e-button variant="filled" toggle>
  <m3e-icon slot="icon" name="play_arrow"></m3e-icon>
  <m3e-icon slot="selected-icon" name="stop"></m3e-icon>
  Start
  <span slot="selected">Stop</span>
</m3e-button>

Use the disabled attribute to disable a button. By default, disabled 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-button variant="filled" disabled>Disabled</m3e-button>
<m3e-button variant="filled" disabled-interactive>Disabled Interactive</m3e-button>

Use the type attribute to control the behavior of a 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.

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-button variant="tonal" href="https://www.google.com" target="_blank">
  Google<m3e-icon slot="trailing-icon" name="open_in_new_window"></m3e-icon>
</m3e-button>

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

Icons 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 button is disabled. If disabled using disabled-interactive, tabindex is retained to convey that the button continues to be interactive.

When href is specified, the ARIA role link is used instead of button to convey the 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 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/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.