API for button

API reference for Angular Material button

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

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

The MatButton class applies to native button elements and captures the appearances for "text button", "outlined button", and "contained button" per the Material Design specification. MatButton additionally captures an additional "flat" appearance, which matches "contained" but without elevation.

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

Exported as: matButton
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.io/components/button/styling.

For information on applying color variants in M3, see https://material.angular.io/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).

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).

Methods
focus

Focuses the button.

Parameters

origin

FocusOrigin = 'program'

options?

FocusOptions

Material Design button component for anchor elements. Anchor elements are used to provide links for the user to navigate across different routes or pages. See https://material.io/components/buttons

The MatAnchor class applies to native anchor elements and captures the appearances for "text button", "outlined button", and "contained button" per the Material Design specification. MatAnchor additionally captures an additional "flat" appearance, which matches "contained" but without elevation.

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

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.io/components/button/styling.

For information on applying color variants in M3, see https://material.angular.io/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).

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).

Methods
focus

Focuses the button.

Parameters

origin

FocusOrigin = 'program'

options?

FocusOptions

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

The MatFabButton class has two appearances: normal and extended.

Selector: button[mat-fab]

Exported as: matButton
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.io/components/button/styling.

For information on applying color variants in M3, see https://material.angular.io/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).

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

Methods
focus

Focuses the button.

Parameters

origin

FocusOrigin = 'program'

options?

FocusOptions

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

Selector: button[mat-mini-fab]

Exported as: matButton
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.io/components/button/styling.

For information on applying color variants in M3, see https://material.angular.io/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).

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).

Methods
focus

Focuses the button.

Parameters

origin

FocusOrigin = 'program'

options?

FocusOptions

Material Design floating action button (FAB) component for anchor elements. Anchor elements are used to provide links for the user to navigate across different routes or pages. See https://material.io/components/buttons-floating-action-button/

The MatFabAnchor class has two appearances: normal and extended.

Selector: a[mat-fab]

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.io/components/button/styling.

For information on applying color variants in M3, see https://material.angular.io/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).

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

Methods
focus

Focuses the button.

Parameters

origin

FocusOrigin = 'program'

options?

FocusOptions

Material Design mini floating action button (FAB) component for anchor elements. Anchor elements are used to provide links for the user to navigate across different routes or pages. See https://material.io/components/buttons-floating-action-button/

Selector: a[mat-mini-fab]

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.io/components/button/styling.

For information on applying color variants in M3, see https://material.angular.io/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).

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).

Methods
focus

Focuses the button.

Parameters

origin

FocusOrigin = 'program'

options?

FocusOptions

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]

Exported as: matButton
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.io/components/button/styling.

For information on applying color variants in M3, see https://material.angular.io/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).

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).

Methods
focus

Focuses the button.

Parameters

origin

FocusOrigin = 'program'

options?

FocusOptions

Material Design icon button component for anchor elements. This button displays a single interaction icon that allows users to navigate across different routes or pages. See https://material.io/develop/web/components/buttons/icon-buttons/

Selector: a[mat-icon-button]

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.io/components/button/styling.

For information on applying color variants in M3, see https://material.angular.io/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).

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).

Methods
focus

Focuses the button.

Parameters

origin

FocusOrigin = 'program'

options?

FocusOptions

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.

disabledInteractive: boolean

Whether disabled buttons should be interactive.

Default FAB options that can be overridden.

Properties
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.io/components/button/styling.

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

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

const MAT_BUTTON_CONFIG: InjectionToken<MatButtonConfig>;

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

const MAT_FAB_DEFAULT_OPTIONS: InjectionToken<MatFabDefaultOptions>;

API reference for Angular Material button-testing

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

Harness for interacting with a mat-button in tests.

Properties
Name Description

static hostSelector: `[mat-button], [mat-raised-button], [mat-flat-button], [mat-icon-button], [mat-stroked-button], [mat-fab], [mat-mini-fab]`

Methods
async
blur

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

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

Clicks the button at its center.

Parameters

location

"center"

Returns
Promise<void>

Promise that resolves when the action completes.

async
click

Clicks the button.

Returns
Promise<void>

Promise that resolves when the action completes.

async
focus

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
Parameters

selector

S

Returns
Promise<HarnessLoader[]>

async
getAllHarnesses
Parameters

query

HarnessQuery<T>

Returns
Promise<T[]>

async
getChildLoader
Parameters

selector

S

Returns
Promise<HarnessLoader>

async
getHarness
Parameters

query

HarnessQuery<T>

Returns
Promise<T>

async
getHarnessOrNull
Parameters

query

HarnessQuery<T>

Returns
Promise<T | null>

async
getText

Gets a promise for the button's label text.

Returns
Promise<string>

async
getVariant

Gets the variant of the button.

Returns
Promise<ButtonVariant>

async
hasHarness
Parameters

query

HarnessQuery<T>

Returns
Promise<boolean>

async
host

Gets a Promise for the TestElement representing the host element of the component.

Returns
Promise<TestElement>

async
isDisabled

Gets a boolean promise indicating if the button is disabled.

Returns
Promise<boolean>

async
isFocused

Whether the button is focused.

Returns
Promise<boolean>

static
with

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.

Returns
HarnessPredicate<T>

a HarnessPredicate configured with the given options.

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

Properties
Name Description

disabled: boolean

Only find instances which match the given disabled state.

text: string | RegExp

Only find instances whose text matches the given value.

variant: ButtonVariant

Only find instances with a variant.

Possible button appearances.

type ButtonVariant = 'basic' | 'raised' | 'flat' | 'icon' | 'stroked' | 'fab' | 'mini-fab';