button.md

Angular Material buttons are native <button> or <a> elements enhanced with Material Design styling.

Native <button> and <a> elements are always used in order to provide the most straightforward and accessible experience for users. A <button> element should be used whenever some action is performed. An <a> element should be used whenever the user will navigate to another view.

There are several button variants, each applied as an attribute:

Attribute	Description
matButton	Rectangular button that can contain text and icons
matIconButton	Smaller, circular button, meant to contain an icon and no text
matFab	Rectangular button w/ elevation and rounded corners, meant to contain an icon. Can be extended to a rectangle to also fit a label
matMiniFab	Smaller variant of matFab

Additionally, the matButton has several appearances that can be set using the matButton attribute, for example matButton="outlined":

Appearance	Description
text	Default appearance. Text buttons are used for the lowest priority actions, especially when presenting multiple options.
filled	High-emphasis buttons used for final or unblocking actions in a flow, such as saving or confirming.
tonal	Medium-emphasis buttons often used for final or unblocking actions in a flow, but with less visual emphasis than a filled button.
outlined	Medium-emphasis buttons often used for actions that need attention but aren't the primary action.
elevated	Medium-emphasis buttons often used when a button requires visual separation from a patterned background.

Extended FAB buttons

Traditional floating action buttons (FAB) buttons are circular and only have space for a single icon. However, you can add the extended attribute to allow the fab to expand into a rounded rectangle shape with space for a text label in addition to the icon. Only full sized fabs support the extended attribute, mini FABs do not.

<button matFab extended>
  <mat-icon>home</mat-icon>
  Home
</button>

You can dynamically expand or collapse the extended FAB using the collapsed input. When collapsed is set to true, the text label is hidden and the extended FAB transitions visually to a circular shape, maintaining the current component structure but occupying less screen estate. By default, collapsed is unconditionally false for all extended FABs.

<button matFab extended [collapsed]="isFabCollapsed">
  <mat-icon>edit</mat-icon>
  Compose
</button>

Icon positioning

Buttons can contain icons alongside text. By default, icons (mat-icon, .material-icons, or elements with the matButtonIcon attribute) are projected before the button label.

<button matButton>
  <mat-icon>favorite</mat-icon>
  Like
</button>

To place an icon after the button label, add the iconPositionEnd attribute to the icon element:

<button matButton>
  Send
  <mat-icon iconPositionEnd>send</mat-icon>
</button>

You can also use both positions at once:

<button matButton>
  <mat-icon>arrow_back</mat-icon>
  Navigate
  <mat-icon iconPositionEnd>arrow_forward</mat-icon>
</button>

If you are using a custom icon element that is not a mat-icon or .material-icons, add the matButtonIcon attribute so that the button can project it into the correct slot:

<button matButton>
  <my-custom-icon matButtonIcon>custom</my-custom-icon>
  Action
</button>

Interactive disabled buttons

Native disabled <button> elements cannot receive focus and do not dispatch any events. This can be problematic in some cases because it can prevent the app from telling the user why the button is disabled. You can use the disabledInteractive input to style the button as disabled but allow for it to receive focus and dispatch events. The button will have aria-disabled="true" for assistive technology. The behavior can be configured globally through the MAT_BUTTON_CONFIG injection token.

Note: Using the disabledInteractive input can result in buttons that previously prevented actions to no longer do so, for example a submit button in a form. When using this input, you should guard against such cases in your component.

Buttons with progress indicators

An element with the progressIndicator attribute may be projected into the button element. When the showProgress input is true this element will be shown over the content of the button and the content of the button will be made invisible.

Accessibility

Angular Material uses native <button> and <a> elements to ensure an accessible experience by default. A <button> element should be used for any interaction that performs an action on the current page. An <a> element should be used for any interaction that navigates to another URL. All standard accessibility best practices for buttons and anchors apply to MatButton.

Capitalization

Using ALL CAPS in the button text itself causes issues for screen-readers, which will read the text character-by-character. It can also cause issues for localization. We recommend not changing the default capitalization for the button text.

Disabling anchors

MatAnchor supports disabling an anchor in addition to the features provided by the native <a> element. When you disable an anchor, the component sets aria-disabled="true" and tabindex="-1". Always test disabled anchors in your application to ensure compatibility with any assistive technology your application supports.

Buttons with icons

Buttons or links containing only icons (such as matFab, matMiniFab, and matIconButton) should be given a meaningful label via aria-label or aria-labelledby. See the documentation for MatIcon for more information on using icons in buttons. Additionally, to be fully accessible the icon should have a minimum touch-target of 48x48 to ensure that the icon is easily clickable particularly on mobile devices and small screens.

Toggle buttons

See the documentation for MatButtonToggle for information on stateful toggle buttons.

Buttons with progress indicators

The element projected using the progressIndicator attribute must not be interactable. When using MatProgressSpinner set tabindex="" to remove the progress indicator for the tab order.