Button • Angular Material

API reference for Angular Material button

import {MatButtonModule} from '@angular/material/button';

Components

`MatButton`

Material Design button component. Users interact with a button to perform an action. See https://m3.material.io/components/buttons/overview

Selector: button[matButton] a[matButton] button[mat-button] button[mat-raised-button] button[mat-flat-button] button[mat-stroked-button] a[mat-button] a[mat-raised-button] a[mat-flat-button] a[mat-stroked-button]

Exported as: matButton, matAnchor

Properties

Name	Description
@Input('matButton') `appearance: MatButtonAppearance \| null`	Appearance of the button.
@Input({ transform: booleanAttribute, alias: 'aria-disabled' }) `ariaDisabled: boolean \| undefined`	`aria-disabled` value of the button.
@Input() `color: string \| null`	Theme color of the button. This API is supported in M2 themes only, it has no effect in M3 themes. For color customization in M3, see https://material.angular.dev/components/button/styling. For information on applying color variants in M3, see https://material.angular.dev/guide/material-2-theming#optional-add-backwards-compatibility-styles-for-color-variants
@Input({ transform: booleanAttribute }) `disableRipple: boolean`	Whether the ripple effect is disabled or not.
@Input({ transform: booleanAttribute }) `disabled: boolean`	Whether the button is disabled.
@Input({ transform: booleanAttribute }) `disabledInteractive: boolean`	Natively disabled buttons prevent focus and any pointer events from reaching the button. In some scenarios this might not be desirable, because it can prevent users from finding out why the button is disabled (e.g. via tooltip). This is also useful for buttons that may become disabled when activated, which would cause focus to be transferred to the document body instead of remaining on the button. Enabling this input will change the button so that it is styled to be disabled and will be marked as `aria-disabled`, but it will allow the button to receive events and focus. Note that by enabling this, you need to set the `tabindex` yourself if the button isn't meant to be tabbable and you have to prevent the button action (e.g. form submissions).
`showProgress: input(false, { transform: booleanAttribute })`	Whether the button is showing a progress indicator.

Methods

focus (origin: `FocusOrigin = 'program'`, options?: `FocusOptions`): `void`
Focuses the button.
Parameters
origin `FocusOrigin = 'program'`
options? `FocusOptions`

setAppearance (appearance: `MatButtonAppearance`): `void`
Programmatically sets the appearance of the button.
Parameters
appearance `MatButtonAppearance`

`MatFabButton`

Material Design floating action button (FAB) component. These buttons represent the primary or most common action for users to interact with. See https://m3.material.io/components/floating-action-button/overview

The MatFabButton class has two appearances: normal and extended.

Selector: button[mat-fab] a[mat-fab] button[matFab] a[matFab]

Exported as: matButton, matAnchor

Properties

Name	Description
@Input({ transform: booleanAttribute, alias: 'aria-disabled' }) `ariaDisabled: boolean \| undefined`	`aria-disabled` value of the button.
@Input() `color: string \| null`	Theme color of the button. This API is supported in M2 themes only, it has no effect in M3 themes. For color customization in M3, see https://material.angular.dev/components/button/styling. For information on applying color variants in M3, see https://material.angular.dev/guide/material-2-theming#optional-add-backwards-compatibility-styles-for-color-variants
@Input({ transform: booleanAttribute }) `disableRipple: boolean`	Whether the ripple effect is disabled or not.
@Input({ transform: booleanAttribute }) `disabled: boolean`	Whether the button is disabled.
@Input({ transform: booleanAttribute }) `disabledInteractive: boolean`	Natively disabled buttons prevent focus and any pointer events from reaching the button. In some scenarios this might not be desirable, because it can prevent users from finding out why the button is disabled (e.g. via tooltip). This is also useful for buttons that may become disabled when activated, which would cause focus to be transferred to the document body instead of remaining on the button. Enabling this input will change the button so that it is styled to be disabled and will be marked as `aria-disabled`, but it will allow the button to receive events and focus. Note that by enabling this, you need to set the `tabindex` yourself if the button isn't meant to be tabbable and you have to prevent the button action (e.g. form submissions).
@Input({ transform: booleanAttribute }) `extended: boolean`
`showProgress: input(false, { transform: booleanAttribute })`	Whether the button is showing a progress indicator.

Methods

focus (origin: `FocusOrigin = 'program'`, options?: `FocusOptions`): `void`
Focuses the button.
Parameters
origin `FocusOrigin = 'program'`
options? `FocusOptions`

`MatMiniFabButton`

Material Design mini floating action button (FAB) component. These buttons represent the primary or most common action for users to interact with. See https://m3.material.io/components/floating-action-button/overview

Selector: button[mat-mini-fab] a[mat-mini-fab] button[matMiniFab] a[matMiniFab]

Exported as: matButton, matAnchor

Properties

Name	Description
@Input({ transform: booleanAttribute, alias: 'aria-disabled' }) `ariaDisabled: boolean \| undefined`	`aria-disabled` value of the button.
@Input() `color: string \| null`	Theme color of the button. This API is supported in M2 themes only, it has no effect in M3 themes. For color customization in M3, see https://material.angular.dev/components/button/styling. For information on applying color variants in M3, see https://material.angular.dev/guide/material-2-theming#optional-add-backwards-compatibility-styles-for-color-variants
@Input({ transform: booleanAttribute }) `disableRipple: boolean`	Whether the ripple effect is disabled or not.
@Input({ transform: booleanAttribute }) `disabled: boolean`	Whether the button is disabled.
@Input({ transform: booleanAttribute }) `disabledInteractive: boolean`	Natively disabled buttons prevent focus and any pointer events from reaching the button. In some scenarios this might not be desirable, because it can prevent users from finding out why the button is disabled (e.g. via tooltip). This is also useful for buttons that may become disabled when activated, which would cause focus to be transferred to the document body instead of remaining on the button. Enabling this input will change the button so that it is styled to be disabled and will be marked as `aria-disabled`, but it will allow the button to receive events and focus. Note that by enabling this, you need to set the `tabindex` yourself if the button isn't meant to be tabbable and you have to prevent the button action (e.g. form submissions).
`showProgress: input(false, { transform: booleanAttribute })`	Whether the button is showing a progress indicator.

Methods

focus (origin: `FocusOrigin = 'program'`, options?: `FocusOptions`): `void`
Focuses the button.
Parameters
origin `FocusOrigin = 'program'`
options? `FocusOptions`

`MatIconButton`

Material Design icon button component. This type of button displays a single interactive icon for users to perform an action. See https://material.io/develop/web/components/buttons/icon-buttons/

Selector: button[mat-icon-button] a[mat-icon-button] button[matIconButton] a[matIconButton]

Exported as: matButton, matAnchor

Properties

Name	Description
@Input({ transform: booleanAttribute, alias: 'aria-disabled' }) `ariaDisabled: boolean \| undefined`	`aria-disabled` value of the button.
@Input() `color: string \| null`	Theme color of the button. This API is supported in M2 themes only, it has no effect in M3 themes. For color customization in M3, see https://material.angular.dev/components/button/styling. For information on applying color variants in M3, see https://material.angular.dev/guide/material-2-theming#optional-add-backwards-compatibility-styles-for-color-variants
@Input({ transform: booleanAttribute }) `disableRipple: boolean`	Whether the ripple effect is disabled or not.
@Input({ transform: booleanAttribute }) `disabled: boolean`	Whether the button is disabled.
@Input({ transform: booleanAttribute }) `disabledInteractive: boolean`	Natively disabled buttons prevent focus and any pointer events from reaching the button. In some scenarios this might not be desirable, because it can prevent users from finding out why the button is disabled (e.g. via tooltip). This is also useful for buttons that may become disabled when activated, which would cause focus to be transferred to the document body instead of remaining on the button. Enabling this input will change the button so that it is styled to be disabled and will be marked as `aria-disabled`, but it will allow the button to receive events and focus. Note that by enabling this, you need to set the `tabindex` yourself if the button isn't meant to be tabbable and you have to prevent the button action (e.g. form submissions).
`showProgress: input(false, { transform: booleanAttribute })`	Whether the button is showing a progress indicator.

Methods

focus (origin: `FocusOrigin = 'program'`, options?: `FocusOptions`): `void`
Focuses the button.
Parameters
origin `FocusOrigin = 'program'`
options? `FocusOptions`

Interfaces

`MatButtonConfig`

Object that can be used to configure the default options for the button component.

Properties

Name	Description
`color: ThemePalette`	Default palette color to apply to buttons.
`defaultAppearance: MatButtonAppearance`	Default appearance for plain buttons (not icon buttons or FABs).
`disabledInteractive: boolean`	Whether disabled buttons should be interactive.

`MatFabDefaultOptions`

Default FAB options that can be overridden.

Properties

Name Description

Name	Description
`color: ThemePalette`	Default theme color of the button. This API is supported in M2 themes only, it has no effect in M3 themes. For color customization in M3, see https://material.angular.dev/components/button/styling. For information on applying color variants in M3, see https://material.angular.dev/guide/material-2-theming#optional-add-backwards-compatibility-styles-for-color-variants.

color: ThemePalette

Default theme color of the button. This API is supported in M2 themes only, it has no effect in M3 themes. For color customization in M3, see https://material.angular.dev/components/button/styling.

For information on applying color variants in M3, see https://material.angular.dev/guide/material-2-theming#optional-add-backwards-compatibility-styles-for-color-variants.

Type aliases

`MatButtonAppearance`

Possible appearances for a MatButton. See https://m3.material.io/components/buttons/overview

type MatButtonAppearance = 'text' | 'filled' | 'elevated' | 'outlined' | 'tonal';

`MatAnchor`

type MatAnchor = MatButton;

`MatFabAnchor`

type MatFabAnchor = MatFabButton;

`MatMiniFabAnchor`

type MatMiniFabAnchor = MatMiniFabButton;

`MatIconAnchor`

type MatIconAnchor = MatIconButton;

Constants

`MAT_BUTTON_CONFIG`

Injection token that can be used to provide the default options the button component.

const MAT_BUTTON_CONFIG: InjectionToken;

`MAT_FAB_DEFAULT_OPTIONS`

Injection token to be used to override the default options for FAB.

const MAT_FAB_DEFAULT_OPTIONS: InjectionToken;

API reference for Angular Material button-testing

import {MatButtonHarness} from '@angular/material/button/testing';

Classes

`MatButtonHarness` extends ContentContainerComponentHarness

Harness for interacting with a mat-button in tests.

Properties

Name	Description
static hostSelector: `.mat-mdc-button-base, [matButton], [mat-button], [matIconButton], [matFab], [matMiniFab], [mat-raised-button], [mat-flat-button], [mat-icon-button], [mat-stroked-button], [mat-fab], [mat-mini-fab]`	Selector for the harness.

Methods

async blur (): `Promise<void>`
Blurs the button and returns a void promise that indicates when the action is complete.
`Promise<void>`	Promise that resolves when the action completes.

async

blur (): Promise<void>

Blurs the button and returns a void promise that indicates when the action is complete.

Returns

Promise<void>

Promise that resolves when the action completes.

async click (relativeX: `number`, relativeY: `number`): `Promise<void>`
Clicks the button at the given position relative to its top-left.
Parameters
relativeX `number`	The relative x position of the click.
relativeY `number`	The relative y position of the click.
Returns
`Promise<void>`	Promise that resolves when the action completes.

async click (location: `"center"`): `Promise<void>`
Clicks the button at its center.
Parameters
location `"center"`
Returns
`Promise<void>`	Promise that resolves when the action completes.

async click (): `Promise<void>`
Clicks the button.
`Promise<void>`	Promise that resolves when the action completes.

async

click (): Promise<void>

Clicks the button.

Returns

Promise<void>

Promise that resolves when the action completes.

async countHarnesses (query: `HarnessQuery<T>`): `Promise<number>`
Returns the number of matching harnesses for the given query within the current harness's content.
Parameters
query `HarnessQuery<T>`	The harness query to search for.
Returns
`Promise<number>`	The number of matching harnesses for the given query.

async focus (): `Promise<void>`
Focuses the button and returns a void promise that indicates when the action is complete.
`Promise<void>`	Promise that resolves when the action completes.

async

focus (): Promise<void>

Focuses the button and returns a void promise that indicates when the action is complete.

Returns

Promise<void>

Promise that resolves when the action completes.

async getAllChildLoaders (selector: `S`): `Promise<HarnessLoader[]>`
Gets a list of `HarnessLoader` for each element matching the given selector under the current harness's cotnent that searches for harnesses under that element.
Parameters
selector `S`	The selector for elements in the component's content.
Returns
`Promise<HarnessLoader[]>`	A list of `HarnessLoader` for each element matching the given selector.

async getAllHarnesses (query: `HarnessQuery<T>`): `Promise<T[]>`
Gets all matching harnesses for the given query within the current harness's content.
Parameters
query `HarnessQuery<T>`	The harness query to search for.
Returns
`Promise<T[]>`	The list of harness matching the given query.

async getAppearance (): `Promise<ButtonAppearance \| null>`
Gets the appearance of the button.
Returns
`Promise<ButtonAppearance \| null>`

async getChildLoader (selector: `S`): `Promise<HarnessLoader>`
Gets a `HarnessLoader` that searches for harnesses under the first element matching the given selector within the current harness's content.
Parameters
selector `S`	The selector for an element in the component's content.
Returns
`Promise<HarnessLoader>`	A `HarnessLoader` that searches for harnesses under the given selector.

async getHarness (query: `HarnessQuery<T>`): `Promise<T>`
Gets the first matching harness for the given query within the current harness's content.
Parameters
query `HarnessQuery<T>`	The harness query to search for.
Returns
`Promise<T>`	The first harness matching the given query.

async getHarnessAtIndex (query: `HarnessQuery<T>`, index: `number`): `Promise<T>`
Gets a matching harness for the given query and index within the current harness's content.
Parameters
query `HarnessQuery<T>`	The harness query to search for.
index `number`	The zero-indexed offset of the component to find.
Returns
`Promise<T>`	The first harness matching the given query.

async getHarnessOrNull (query: `HarnessQuery<T>`): `Promise<T \| null>`
Gets the first matching harness for the given query within the current harness's content.
Parameters
query `HarnessQuery<T>`	The harness query to search for.
Returns
`Promise<T \| null>`	The first harness matching the given query, or null if none is found.

async getText (): `Promise<string>`
Gets a promise for the button's label text.
Returns
`Promise<string>`

async getType (): `Promise<ButtonType \| null>`
Gets the type of the button. Supported values are 'button', 'submit', and 'reset'.
Returns
`Promise<ButtonType \| null>`

async getVariant (): `Promise<ButtonVariant>`
Gets the variant of the button.
Returns
`Promise<ButtonVariant>`

async hasHarness (query: `HarnessQuery<T>`): `Promise<boolean>`
Checks whether there is a matching harnesses for the given query within the current harness's content.
Parameters
query `HarnessQuery<T>`	The harness query to search for.
Returns
`Promise<boolean>`	Whether there is matching harnesses for the given query.

async host (): `Promise<TestElement>`
Gets a `Promise` for the `TestElement` representing the host element of the component.
Returns
`Promise<TestElement>`

async isDisabled (): `Promise<boolean>`
Gets a boolean promise indicating if the button is disabled.
Returns
`Promise<boolean>`

async isFocused (): `Promise<boolean>`
Whether the button is focused.
Returns
`Promise<boolean>`

async isShowingProgress (): `Promise<boolean>`
Whether the button is showing a progress indicator.
Returns
`Promise<boolean>`

static with (options: `ButtonHarnessFilters = {}`): `HarnessPredicate<T>`
Gets a `HarnessPredicate` that can be used to search for a button with specific attributes.
Parameters
options `ButtonHarnessFilters = {}`	Options for narrowing the search: `selector` finds a button whose host element matches the given selector. `text` finds a button with specific text content. `variant` finds buttons matching a specific variant. `appearance` finds buttons matching a specific appearance.
Returns
`HarnessPredicate<T>`	a `HarnessPredicate` configured with the given options.

Interfaces

`ButtonHarnessFilters`

A set of criteria that can be used to filter a list of button harness instances.

Properties

Name	Description
`appearance: ButtonAppearance`	Only find instances with a specific appearance.
`buttonType: ButtonType`	Only find instances with the specified type.
`disabled: boolean`	Only find instances which match the given disabled state.
`iconName: string \| RegExp`	Only find instances that contain an icon whose name matches the given value.
`text: string \| RegExp`	Only find instances whose text matches the given value.
`variant: ButtonVariant`	Only find instances with a variant.

Type aliases

`ButtonVariant`

Possible button variants.

type ButtonVariant = 'basic' | 'icon' | 'fab' | 'mini-fab';

`ButtonAppearance`

Possible button appearances.

type ButtonAppearance = 'text' | 'filled' | 'elevated' | 'outlined' | 'tonal';

`ButtonType`

Possible button types.

type ButtonType = 'button' | 'submit' | 'reset';

Testing

API reference for Angular Material button

Components link

MatButton link

Properties

Methods

MatFabButton link

Properties

Methods

MatMiniFabButton link

Properties

Methods

MatIconButton link

Properties

Methods

Interfaces link

MatButtonConfig link

Properties

MatFabDefaultOptions link

Properties

Type aliases link

MatButtonAppearance link

MatAnchor link

MatFabAnchor link

MatMiniFabAnchor link

MatIconAnchor link

Constants link

MAT_BUTTON_CONFIG link

MAT_FAB_DEFAULT_OPTIONS link

API reference for Angular Material button-testing

Classes link

MatButtonHarness extends ContentContainerComponentHarness link

Properties

Methods

Interfaces link

ButtonHarnessFilters link

Properties

Type aliases link

ButtonVariant link

ButtonAppearance link

ButtonType link

Components

`MatButton`

`MatFabButton`

`MatMiniFabButton`

`MatIconButton`

Interfaces

`MatButtonConfig`

`MatFabDefaultOptions`

Type aliases

`MatButtonAppearance`

`MatAnchor`

`MatFabAnchor`

`MatMiniFabAnchor`

`MatIconAnchor`

Constants

`MAT_BUTTON_CONFIG`

`MAT_FAB_DEFAULT_OPTIONS`

Classes

`MatButtonHarness` extends ContentContainerComponentHarness

Interfaces

`ButtonHarnessFilters`

Type aliases

`ButtonVariant`

`ButtonAppearance`

`ButtonType`