# Icon Buttons
Icon buttons help people take supplementary actions with a single tap.
**Example: A row of icon buttons, one for each color**
```html
favorite
share
settings
more_vert
```
## 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](#tooltip) so the action is named while hovering or focusing the button.
* **Pick the color by emphasis.** [Filled](#colors) is the most prominent, [tonal](#colors) and [outlined](#colors) are medium, and the standard color suits the lowest priority.
* **Show state with a toggle.** A [toggle](#toggle) button uses the outlined icon when unselected and the filled icon when selected.
## Anatomy
An icon button is one element that holds an icon (default slot). It renders a native `` or, with `href`, a link.
**Example: A filled icon button with a send icon**
```html
send
```
## Examples
### Colors
Choose one of four colors with the `color` attribute: filled, tonal, outlined, or standard (the default).
**Example: Filled, tonal, outlined and standard icon buttons**
```html
videocam
videocam
videocam
videocam
```
### Sizes
Set `size` to `xs`, `sm` (default), `md`, `lg`, or `xl`.
**Example: Filled icon buttons from extra small to extra large**
```html
add
add
add
add
add
```
### Widths
Set `width` to `narrow` or `wide`. The default width sits in between.
**Example: Narrow, default and wide icon buttons**
```html
edit
edit
edit
```
### Square shape
Add `square` to change the shape of the button from round to square.
**Example: A filled icon button with a square shape**
```html
delete
```
### 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.
**Example: An unselected and a selected toggle icon button**
```html
favorite
bookmark
```
### 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.
**Example: An icon button with a tooltip**
```html
favorite
```
### Links
Set `href` to render the button as a link. Use `target` and `rel` as you would on an anchor.
**Example: An icon button that links to another page**
```html
open_in_new
```
### 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.
**Example: A filled icon button at density -2**
```html
search
```
### 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.
**Example: A disabled icon button and a soft-disabled icon button**
```html
share
share
```
## Accessibility
* An icon button has no visible text, so always give it an [`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/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](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls) allows.
* Toggle buttons expose their state with `aria-pressed`.
**Example: A toggle icon button that exposes its pressed state**
```html
favorite
```
## API reference
### <md-gb-icon-button>
A Material Design component.
#### Properties
| Property | Attribute | Type | Default |
| --- | --- | --- | --- |
| colorThe color of the button. | color | IconButtonColor | 'standard' |
| densityThe 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 | |
| downloadThe filename to use when downloading the linked resource. | download | string | '' |
| hrefThe URL that the link button points to. | href | string | '' |
| referrerPolicySets the underlying HTMLAnchorElement's referrerpolicy attribute when href is set. | referrerpolicy | string | '' |
| relSets the underlying HTMLAnchorElement's rel attribute when href is set. | rel | string | '' |
| selectedWhether or not the button is selected, when type="toggle". TODO: replace reflected [selected] with :state(selected) | selected | boolean | false |
| sizeThe size of the button. | size | IconButtonSize | 'sm' |
| softDisabledWhether or not the button is "soft-disabled" (disabled but still focusable). | soft-disabled | boolean | false |
| squareChanges the shape of the button to be square. | square | boolean | false |
| targetWhere to display the linked href URL for a link button. | target | "" | "_blank" | "_parent" | "_self" | "_top" | '' |
| tooltipShows 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 |
| typeA 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 | |
| unfilledIconSet 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 |
| widthChanges the width of the button. | width | IconButtonWidth | '' |
#### Slots
| Slot | Description |
| --- | --- |
| default | Used to display an icon. |
#### Events
| Event | Description |
| --- | --- |
| changeEvent | Fired when a toggle button is selected or unselected. |
| inputInputEvent | Fired when a toggle icon button is selected or unselected. |
#### CSS parts
| Part | Description |
| --- | --- |
| ::part(icon-btn) | The icon button's root element. |
#### 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 | |