toc

Buttons

Buttons help people initiate actions, from sending an email, to sharing a document, to liking a post.

Save

Cancel

<md-gb-button color="filled">Save</md-gb-button>
<md-gb-button color="outlined">Cancel</md-gb-button>

Install with shadcn/ui: npx shadcn@latest add https://material-web.dev/3.0/r/md-button.json (setup)

Usage guidelines

Link to “Usage guidelines”

Label the action. A button's text describes what happens when it is pressed, such as "Save" or "Join now".
Match emphasis to importance. Use filled for the final action of a flow, tonal and outlined for medium emphasis, and text for the lowest priority.
Use elevated sparingly. Elevated buttons add a shadow, so reserve them for buttons that need separation from a patterned background.
Add an icon to draw attention. An icon can help communicate the action.

Anatomy

Link to “Anatomy”

A button is one element holding a label and an optional icon (default slot). It renders a native <button> or, with href, a link.

send Send

<md-gb-button color="filled">
  <md-gb-icon>send</md-gb-icon>
  Send
</md-gb-button>

Examples

Link to “Examples”

Colors

Link to “Colors”

Choose one of five colors with the color attribute: filled, elevated, tonal, outlined, or text.

Elevated

Filled

Tonal

Outlined

Text

<md-gb-button color="elevated">Elevated</md-gb-button>
<md-gb-button color="filled">Filled</md-gb-button>
<md-gb-button color="tonal">Tonal</md-gb-button>
<md-gb-button color="outlined">Outlined</md-gb-button>
<md-gb-button color="text">Text</md-gb-button>

Sizes

Link to “Sizes”

Set size to xs, sm (default), md, lg, or xl.

Small

Medium

Large

<md-gb-button size="xs">XS</md-gb-button>
<md-gb-button size="sm">Small</md-gb-button>
<md-gb-button size="md">Medium</md-gb-button>
<md-gb-button size="lg">Large</md-gb-button>
<md-gb-button size="xl">XL</md-gb-button>

With an icon

Link to “With an icon”

Put an md-gb-icon before the label, or after it for an action that leaves the page.

send Send

Open open_in_new

<md-gb-button color="tonal">
  <md-gb-icon>send</md-gb-icon>
  Send
</md-gb-button>
<md-gb-button color="text">
  Open
  <md-gb-icon>open_in_new</md-gb-icon>
</md-gb-button>

Square shape

Link to “Square shape”

Add square to change the shape of the button from round to square.

Square

<md-gb-button color="filled" square>Square</md-gb-button>

Toggle

Link to “Toggle”

Set type="toggle" to make a button that stays selected after it is pressed. Add selected for the initial state.

favorite

<md-gb-button type="toggle" color="outlined" aria-label="Favorite">
  <md-gb-icon>favorite</md-gb-icon>
</md-gb-button>

Disabled and soft-disabled

Link to “Disabled and soft-disabled”

A disabled button can't be focused with the keyboard. A soft-disabled button stays focusable, which helps discoverability in toolbars.

Disabled

Soft-disabled

<md-gb-button color="filled" disabled>Disabled</md-gb-button>
<md-gb-button color="filled" soft-disabled>Soft-disabled</md-gb-button>

Link to “Opening a popover or menu”

Like a native button, an md-gb-button (and md-gb-icon-button) takes popovertarget (with popovertargetaction) or commandfor (with command) naming an element in the same tree. A menu opened this way also opens with the arrow keys.

Options

<md-gb-button color="tonal" popovertarget="button-menu">Options</md-gb-button>
<md-gb-menu id="button-menu">
  <md-gb-menu-item>Rename</md-gb-menu-item>
  <md-gb-menu-item>Duplicate</md-gb-menu-item>
</md-gb-menu>

Accessibility

Link to “Accessibility”

Buttons need a visible label; add an aria-label to icon-only buttons or when the label needs to be more descriptive.
Buttons activate with Enter and Space and are reachable with Tab.
Disabled buttons leave the tab order. Use soft-disabled to keep one focusable, as the ARIA guidance on disabled controls allows.
Toggle buttons expose their state with aria-pressed.

Add

<md-gb-button aria-label="Add a new contact" color="elevated">Add</md-gb-button>

Compatibility

Link to “Compatibility”

Material Design 3Spec checked94% tokens

173 of 348 buildable spec units are tested, 8 are excluded with a written reason and 0 are uncovered (the target is 0). 158 of 168 token declarations match the spec (94%), and 10 have no spec token.

buttons on m3.material.io (opens in a new tab) How compliance is measured

BaselineWidely availableChrome 124Edge 124Firefox 125Safari 17.4

The component’s own CSS and JavaScript rely only on web platform features that are Baseline widely available: it works in Chrome 124, Edge 124, Firefox 125, Safari 17.4 and later.

Newer features it uses where the browser has them (progressive enhancements):

Cursor styles (opens in a new tab) Limited availability degrades safely where it is missing
commandForElement (invoker commands) (opens in a new tab) Newly available JavaScript, feature-detected or optional

Browser support Learn more about Baseline (opens in a new tab)

WAI-ARIAaxe and ARIA 1.3 passButtonLink

Roles the component renders: button (opens in a new tab), link (opens in a new tab).

Follows the WAI-ARIA Authoring Practices: Button (opens in a new tab), Link (opens in a new tab).

5 rendered states run through axe-core and the WAI-ARIA 1.3 role and attribute rules in a real browser, with no known gaps.

WAI-ARIA 1.3 (opens in a new tab) ARIA Authoring Practices (opens in a new tab) Accessibility

Lighthouse98 · 100 · 100 · 100

Performance
Accessibility
Best practices
SEO

Audits under 90:

Eliminate render-blocking resources
Minify JavaScript
Reduce unused CSS
Enable text compression
Network dependency tree
Render blocking requests

Lighthouse 12.8.2 (desktop, 2026-11-08) on the component alone: its first example on a page of its own, without this site's shell. The modules are the development build (not bundled or minified), so the performance score is indicative.

Open the test page About Lighthouse (opens in a new tab)

API reference

Link to “API reference”

<md-gb-button>

Link to “<md-gb-button>”

A Material Design button.

Properties

Link to “Properties”

Property	Attribute	Type	Default
`color` The color of the button.	`color`	`"filled"`	"elevated"
`download` The filename to use when downloading the linked resource. If not specified, the browser will determine a filename. This is only applicable when the button is used as a link (`href` is set).	`download`	`string`	`''`
`href` The URL that the link button points to.	`href`	`string`	`''`
`referrerPolicy` Sets the underlying `HTMLAnchorElement`'s `referrerpolicy` attribute when `href` is set.	`referrerpolicy`	`string`	`''`
`rel` Sets the underlying `HTMLAnchorElement`'s `rel` attribute when `href` is set.	`rel`	`string`	`''`
`selected` Whether or not the button is selected, when `type="toggle"`. TODO: replace reflected `[selected]` with `:state(selected)`	`selected`	`boolean`	`false`
`size` The size of the button.	`size`	`"sm"`	"md"
`softDisabled` Whether or not the button is "soft-disabled" (disabled but still focusable). Use this when a button needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed.	`soft-disabled`	`boolean`	`false`
`square` Changes the shape of the button to be square.	`square`	`boolean`	`false`
`target` Where to display the linked `href` URL for a link button. Common options include `_blank` to open in a new tab.	`target`	`""`	"_blank"
`type` A string indicating the behavior of the button. - "submit" (default): A button that submits its associated form. - "reset": A button that resets its associated form. - "button": A normal button. - "toggle": A toggle button using the `selected` property. - "link": An anchor link (`<a>`). Type is always "link" when `href` is set.	`type`	`string`
`unfilledIcon` Set when the icon has no filled version: a selected toggle button then shows the icon in semibold weight instead of filled.	`unfilled-icon`	`boolean`	`false`

Slots

Link to “Slots”

Slot	Description
default	Used to display a label and optional icon.
`container`	Used to set a custom background container for the button.

Events

Link to “Events”

Event	Description
`change` Event	Fired when a toggle button is selected or unselected.
`input` InputEvent	Fired when a toggle button is selected or unselected.

CSS parts

Link to “CSS parts”

Part	Description
`::part(btn)`	The button's root element.

CSS custom properties

Link to “CSS custom properties”

Property	Description
`--container-color`
`--container-elevation`
`--container-height`
`--container-shape`	The resolved shape; defaults to the round or square shape.
`--container-shape-round`
`--container-shape-square`
`--icon-color`
`--icon-label-space`
`--icon-size`
`--label-text`
`--label-text-axes`
`--label-text-color`
`--label-text-tracking`
`--leading-space`
`--md-icon-fill`
`--outline-color`
`--outline-width`
`--state-layer-color`
`--trailing-space`