Skip to content

Latest commit

 

History

History
523 lines (395 loc) · 17.9 KB

icon-button.md

File metadata and controls

523 lines (395 loc) · 17.9 KB

Icon Buttons

This documentation is fully rendered on the Material Web catalog.

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

The top half of a phone application with a back icon button at the top left and three icon buttons on the top right, heart, share, and three dot.

Types

Side by side view of standard and contained icon buttons

  1. Icon Button
  2. Filled Icon Button
  3. Filled Tonal Icon Button
  4. Outlined Icon Button

Usage

Use icon buttons to display actions in a compact layout. Icon buttons can represent opening actions such as opening an overflow menu or search, or represent binary actions that can be toggled on and off, such as favorite or bookmark.

Icon buttons can be grouped together or they can stand alone.

To use icons by name, see the Icon documentation for loading the icon font.

A row of icon buttons

<md-icon-button>
  <md-icon>check</md-icon>
</md-icon-button>
<md-filled-icon-button>
  <md-icon>check</md-icon>
</md-filled-icon-button>
<md-filled-tonal-icon-button>
  <md-icon>check</md-icon>
</md-filled-tonal-icon-button>
<md-outlined-icon-button>
  <md-icon>check</md-icon>
</md-outlined-icon-button>

Links

Add an href and optionally a target attribute to turn the icon button into a link.

<md-icon-button href="https://google.com">
  <md-icon>check</md-icon>
</md-icon-button>

Toggle

Two rows of toggling icon buttons, the top row is unselected and the bottom row is selected

Toggle icon buttons allow a single choice to be selected or deselected, such as adding or removing something from favorites.

Add a second icon in the slot="selected" slot to change the icon when selected. Toggle icon buttons can be pre-selected by adding the selected attribute.

<div>
  <md-icon-button toggle>
    <md-icon>close</md-icon>
    <md-icon slot="selected">check</md-icon>
  </md-icon-button>
  <md-filled-icon-button toggle>
    <md-icon>close</md-icon>
    <md-icon slot="selected">check</md-icon>
  </md-filled-icon-button>
  <md-filled-tonal-icon-button toggle>
    <md-icon>close</md-icon>
    <md-icon slot="selected">check</md-icon>
  </md-filled-tonal-icon-button>
  <md-outlined-icon-button toggle>
    <md-icon>close</md-icon>
    <md-icon slot="selected">check</md-icon>
  </md-outlined-icon-button>
</div>
<div>
  <md-icon-button toggle selected>
    <md-icon>close</md-icon>
    <md-icon slot="selected">check</md-icon>
  </md-icon-button>
  <md-filled-icon-button toggle selected>
    <md-icon>close</md-icon>
    <md-icon slot="selected">check</md-icon>
  </md-filled-icon-button>
  <md-filled-tonal-icon-button toggle selected>
    <md-icon>close</md-icon>
    <md-icon slot="selected">check</md-icon>
  </md-filled-tonal-icon-button>
  <md-outlined-icon-button toggle selected>
    <md-icon>close</md-icon>
    <md-icon slot="selected">check</md-icon>
  </md-outlined-icon-button>
</div>

Accessibility

Add an aria-label attribute to icon buttons whose labels need a more descriptive label.

<md-icon-button aria-label="Search for Contact">
  <md-icon>search</md-icon>
</md-icon-button>

Toggle

Add an aria-label-selected attribute to toggle buttons whose labels need a more descriptive label when selected.

<md-icon-button toggle
  aria-label="Unselected"
  aria-label-selected="Selected">
  <md-icon>close</md-icon>
  <md-icon slot="selected">check</md-icon>
</md-icon-button>

Icon Button

Standard icon buttons do not have a background or outline, and have the lowest emphasis of the icon buttons.

A check icon

<md-icon-button>
  <md-icon>check</md-icon>
</md-icon-button>

Filled Icon Button

A circular button with a check icon

Filled icon buttons have higher visual impact and are best for high emphasis actions.

<md-filled-icon-button>
  <md-icon>check</md-icon>
</md-filled-icon-button>

Filled Tonal Icon Button

A filled tonal icon button with a check icon

Filled tonal icon buttons are a middle ground between filled and outlined icon buttons. They're useful in contexts where the button requires slightly more emphasis than an outline would give, such as a secondary action paired with a high emphasis action.

<md-filled-tonal-icon-button>
  <md-icon>check</md-icon>
</md-filled-tonal-icon-button>

Outlined Icon Button

An outlined circular icon button with a check icon

Outlined icon buttons are medium-emphasis buttons. They're useful when an icon button needs more emphasis than a standard icon button but less than a filled or filled tonal icon button.

<md-outlined-icon-button>
  <md-icon>check</md-icon>
</md-outlined-icon-button>

Theming

Icon Button supports Material theming and can be customized in terms of color, and shape.

Icon Button tokens

Token Default value
--md-icon-button-icon-color --md-sys-color-on-surface-variant
--md-icon-button-state-layer-shape 9999px
--md-icon-button-icon-size 24px

Icon Button example

Image of a standard icon button with a different theme applied

<style>
:root {
  --md-icon-button-icon-size: 32px;
  --md-sys-color-on-surface-variant: #dc362e;
  background-color: #fff8f6;
}
</style>

<md-icon-button>
  <md-icon>check</md-icon>
</md-icon-button>

Filled Icon Button tokens

Token Default value
--md-filled-icon-button-selected-container-color --md-sys-color-primary
--md-filled-icon-button-container-shape 9999px
--md-filled-icon-button-container-width 40px
--md-filled-icon-button-container-height 40px
--md-filled-icon-button-icon-size 24px

Filled Icon Button example

Image of a filled icon button with a different theme applied

<style>
:root {
  --md-filled-icon-button-container-width: 80px;
  --md-filled-icon-button-container-height: 80px;
  --md-filled-icon-button-icon-size: 40px;
  --md-filled-icon-button-container-shape: 0px;
  --md-sys-color-primary: #dc362e;
  background-color: #fff8f6;
}
</style>
<md-filled-icon-button>
  <md-icon>check</md-icon>
</md-filled-icon-button>

Filled Tonal Icon Button tokens

Token Default value
--md-filled-tonal-icon-button-selected-container-color --md-sys-color-secondary-container
--md-filled-tonal-icon-button-container-shape 9999px
--md-filled-tonal-icon-button-container-width 40px
--md-filled-tonal-icon-button-container-height 40px
--md-filled-tonal-icon-button-icon-size 24px

Filled Tonal Icon Button example

Image of a filled tonal icon button with a different theme applied

<style>
:root {
  --md-filled-tonal-icon-button-container-width: 80px;
  --md-filled-tonal-icon-button-container-height: 80px;
  --md-filled-tonal-icon-button-container-shape: 0px;
  --md-filled-tonal-icon-button-icon-size: 40px;
  --md-sys-color-secondary-container: #006A6A;
}
</style>
<md-filled-tonal-icon-button>
  <md-icon>check</md-icon>
</md-filled-tonal-icon-button>

Outlined Icon Button tokens

Token Default value
--md-outlined-icon-button-outline-color --md-sys-color-outline
--md-outlined-icon-button-outline-width 1px
--md-outlined-icon-button-container-shape 9999px
--md-outlined-icon-button-container-width 40px
--md-outlined-icon-button-container-height 40px
--md-outlined-icon-button-icon-size 24px

Outlined Icon Button example

Image of an outlined icon button with a different theme applied

<style>
:root {
  --md-outlined-icon-button-container-width: 80px;
  --md-outlined-icon-button-container-height: 80px;
  --md-outlined-icon-button-container-shape: 0px;
  --md-outlined-icon-button-icon-size: 40px;
  --md-outlined-icon-button-outline-width: 4px;
  --md-sys-color-outline: #006A6A;
}
</style>
<md-outlined-icon-button>
  <md-icon>check</md-icon>
</md-outlined-icon-button>

API

MdIconButton <md-icon-button>

Properties

Property Attribute Type Default Description
disabled disabled boolean false Disables the icon button and makes it non-interactive.
flipIconInRtl flip-icon-in-rtl boolean false Flips the icon if it is in an RTL context at startup.
href href string '' Sets the underlying HTMLAnchorElement's href resource attribute.
target target string '' Sets the underlying HTMLAnchorElement's target attribute.
ariaLabelSelected aria-label-selected string '' The aria-label of the button when the button is toggleable and selected.
toggle toggle boolean false When true, the button will toggle between selected and unselected states
selected selected boolean false Sets the selected state. When false, displays the default icon. When true, displays the selected icon, or the default icon If no slot="selected" icon is provided.
type type string 'submit'
value value string ''
name string undefined
form HTMLFormElement undefined
labels NodeList undefined

MdFilledIconButton <md-filled-icon-button>

Properties

Property Attribute Type Default Description
disabled disabled boolean false Disables the icon button and makes it non-interactive.
flipIconInRtl flip-icon-in-rtl boolean false Flips the icon if it is in an RTL context at startup.
href href string '' Sets the underlying HTMLAnchorElement's href resource attribute.
target target string '' Sets the underlying HTMLAnchorElement's target attribute.
ariaLabelSelected aria-label-selected string '' The aria-label of the button when the button is toggleable and selected.
toggle toggle boolean false When true, the button will toggle between selected and unselected states
selected selected boolean false Sets the selected state. When false, displays the default icon. When true, displays the selected icon, or the default icon If no slot="selected" icon is provided.
type type string 'submit'
value value string ''
name string undefined
form HTMLFormElement undefined
labels NodeList undefined

MdFilledTonalIconButton <md-filled-tonal-icon-button>

Properties

Property Attribute Type Default Description
disabled disabled boolean false Disables the icon button and makes it non-interactive.
flipIconInRtl flip-icon-in-rtl boolean false Flips the icon if it is in an RTL context at startup.
href href string '' Sets the underlying HTMLAnchorElement's href resource attribute.
target target string '' Sets the underlying HTMLAnchorElement's target attribute.
ariaLabelSelected aria-label-selected string '' The aria-label of the button when the button is toggleable and selected.
toggle toggle boolean false When true, the button will toggle between selected and unselected states
selected selected boolean false Sets the selected state. When false, displays the default icon. When true, displays the selected icon, or the default icon If no slot="selected" icon is provided.
type type string 'submit'
value value string ''
name string undefined
form HTMLFormElement undefined
labels NodeList undefined

MdOutlinedIconButton <md-outlined-icon-button>

Properties

Property Attribute Type Default Description
disabled disabled boolean false Disables the icon button and makes it non-interactive.
flipIconInRtl flip-icon-in-rtl boolean false Flips the icon if it is in an RTL context at startup.
href href string '' Sets the underlying HTMLAnchorElement's href resource attribute.
target target string '' Sets the underlying HTMLAnchorElement's target attribute.
ariaLabelSelected aria-label-selected string '' The aria-label of the button when the button is toggleable and selected.
toggle toggle boolean false When true, the button will toggle between selected and unselected states
selected selected boolean false Sets the selected state. When false, displays the default icon. When true, displays the selected icon, or the default icon If no slot="selected" icon is provided.
type type string 'submit'
value value string ''
name string undefined
form HTMLFormElement undefined
labels NodeList undefined