Skip to main content brightness_auto motion_photos_off palette download more_vert
toc

Icon Buttons

Icon buttons help people take supplementary actions with a single tap.

View as Markdown

favorite share settings more_vert 
<md-gb-icon-button color="filled" aria-label="Favorite">
  <md-gb-icon>favorite</md-gb-icon>
</md-gb-icon-button>
<md-gb-icon-button color="tonal" aria-label="Share">
  <md-gb-icon>share</md-gb-icon>
</md-gb-icon-button>
<md-gb-icon-button color="outlined" aria-label="Settings">
  <md-gb-icon>settings</md-gb-icon>
</md-gb-icon-button>
<md-gb-icon-button aria-label="More options">
  <md-gb-icon>more_vert</md-gb-icon>
</md-gb-icon-button>

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

Usage guidelines

Link to “Usage guidelines”
  • Use a clear icon. Pick a system icon whose meaning people already know, and give the button an accessible name that describes the action.
  • Describe the action on hover. On the web, add a tooltip so the action is named while hovering or focusing the button.
  • Pick the color by emphasis. Filled is the most prominent, tonal and outlined are medium, and the standard color suits the lowest priority.
  • Show state with a toggle. A toggle button uses the outlined icon when unselected and the filled icon when selected.

Anatomy

Link to “Anatomy”

An icon button is one element that holds an icon (default slot). It renders a native <button> or, with href, a link.

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

Examples

Link to “Examples”

Colors

Link to “Colors”

Choose one of four colors with the color attribute: filled, tonal, outlined, or standard (the default).

videocam videocam videocam videocam 
<md-gb-icon-button color="filled" aria-label="Video call">
  <md-gb-icon>videocam</md-gb-icon>
</md-gb-icon-button>
<md-gb-icon-button color="tonal" aria-label="Video call">
  <md-gb-icon>videocam</md-gb-icon>
</md-gb-icon-button>
<md-gb-icon-button color="outlined" aria-label="Video call">
  <md-gb-icon>videocam</md-gb-icon>
</md-gb-icon-button>
<md-gb-icon-button aria-label="Video call">
  <md-gb-icon>videocam</md-gb-icon>
</md-gb-icon-button>

Sizes

Link to “Sizes”

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

add add add add add 
<md-gb-icon-button color="filled" size="xs" aria-label="Add">
  <md-gb-icon>add</md-gb-icon>
</md-gb-icon-button>
<md-gb-icon-button color="filled" aria-label="Add">
  <md-gb-icon>add</md-gb-icon>
</md-gb-icon-button>
<md-gb-icon-button color="filled" size="md" aria-label="Add">
  <md-gb-icon>add</md-gb-icon>
</md-gb-icon-button>
<md-gb-icon-button color="filled" size="lg" aria-label="Add">
  <md-gb-icon>add</md-gb-icon>
</md-gb-icon-button>
<md-gb-icon-button color="filled" size="xl" aria-label="Add">
  <md-gb-icon>add</md-gb-icon>
</md-gb-icon-button>

Widths

Link to “Widths”

Set width to narrow or wide. The default width sits in between.

edit edit edit 
<md-gb-icon-button color="tonal" width="narrow" aria-label="Edit">
  <md-gb-icon>edit</md-gb-icon>
</md-gb-icon-button>
<md-gb-icon-button color="tonal" aria-label="Edit">
  <md-gb-icon>edit</md-gb-icon>
</md-gb-icon-button>
<md-gb-icon-button color="tonal" width="wide" aria-label="Edit">
  <md-gb-icon>edit</md-gb-icon>
</md-gb-icon-button>

Square shape

Link to “Square shape”

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

delete 
<md-gb-icon-button color="filled" square aria-label="Delete">
  <md-gb-icon>delete</md-gb-icon>
</md-gb-icon-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. The selected button shows the filled icon; if an icon has no filled version, add unfilled-icon and it gets a heavier weight instead.

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

Tooltip

Link to “Tooltip”

Add tooltip to show the button's aria-label on hover and keyboard focus. Write the label as the action, not the icon's name.

favorite 
<md-gb-icon-button tooltip aria-label="Add to favorites">
  <md-gb-icon>favorite</md-gb-icon>
</md-gb-icon-button>
Link to “Links”

Set href to render the button as a link. Use target and rel as you would on an anchor.

open_in_new 
<md-gb-icon-button href="https://m3.material.io/components/icon-buttons" target="_blank" aria-label="Open the guidelines">
  <md-gb-icon>open_in_new</md-gb-icon>
</md-gb-icon-button>

Density

Link to “Density”

Set density from 0 (default) down to -3 to remove 4px of height per step. The touch target stays at least 48px. Keep it off by default and let people opt in.

search 
<md-gb-icon-button color="filled" density="-2" aria-label="Search">
  <md-gb-icon>search</md-gb-icon>
</md-gb-icon-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.

share share 
<md-gb-icon-button color="filled" disabled aria-label="Share">
  <md-gb-icon>share</md-gb-icon>
</md-gb-icon-button>
<md-gb-icon-button color="filled" soft-disabled aria-label="Share">
  <md-gb-icon>share</md-gb-icon>
</md-gb-icon-button>

Accessibility

Link to “Accessibility”
  • An icon button has no visible text, so always give it an aria-label that describes the action.
  • Icon 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.
favorite 
<md-gb-icon-button type="toggle" aria-label="Add to favorites">
  <md-gb-icon>favorite</md-gb-icon>
</md-gb-icon-button>

Compatibility

Link to “Compatibility”
Material Design 3Spec checked93% tokens

168 of 292 buildable spec units are tested, 2 are excluded with a written reason and 0 are uncovered (the target is 0). 114 of 122 token declarations match the spec (93%), and 8 have no spec token.

icon-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):

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:

  • Elements with visible text labels do not have matching accessible names.
  • Eliminate render-blocking resources
  • Minify JavaScript
  • Reduce unused JavaScript
  • 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-icon-button>

Link to “<md-gb-icon-button>”

A Material Design component.

Properties

Link to “Properties”
Property Attribute Type Default
color
The color of the button.		 color IconButtonColor 'standard'
density
The density, from 0 (default) to -3. Each step down removes 4px from the container height (and the width of a default-width button); the icon keeps its size and the touch target stays at least 48px. Values are clamped to that range. Density 0 inherits the density of an enclosing md-gb-button-group. icon-buttons.md: don't apply density by default; let people opt in to a denser layout.		 density Density
download
The filename to use when downloading the linked resource.		 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 IconButtonSize 'sm'
softDisabled
Whether or not the button is "soft-disabled" (disabled but still focusable).		 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.		 target "" "_blank"
tooltip
Shows a tooltip with the button's accessibility label (aria-label) on hover and keyboard focus. The label should describe the action, not name the icon.		 tooltip boolean false
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
width
Changes the width of the button.		 width IconButtonWidth ''

Slots

Link to “Slots”
Slot Description
default Used to display an icon.

Events

Link to “Events”
Event Description
change
Event		 Fired when a toggle button is selected or unselected.
input
InputEvent		 Fired when a toggle icon button is selected or unselected.

CSS parts

Link to “CSS parts”
Part Description
::part(icon-btn) The icon button's root element.

CSS custom properties

Link to “CSS custom properties”
Property Description
--container-color
--container-height Container height at density 0.
--container-shape The resolved shape; defaults to the round or square shape.
--container-shape-round
--container-shape-square
--density-step Container height removed per density step.
--icon-color
--icon-size
--leading-space
--md-icon-fill
--outline-color
--outline-width
--target-size The minimum touch target size, kept at any density.
--trailing-space
Install Material Web 3.0

Your browser did not offer to install the docs as an app. Install them from the browser instead:

Close Send feedback
Bug Documentation Idea

Opens a new GitHub issue for material-components/material-web in a new tab, with this filled in.

Cancel Open issue