API for tabs

API reference for Angular Material tabs

import {MatTabsModule} from '@angular/material/tabs';

Decorates the ng-template tags and reads out the template from it.

Selector: [matTabContent]

Properties
Name Description

template: inject<TemplateRef<any>>(TemplateRef)

Used to flag tab labels for use with the portal directive

Selector: [mat-tab-label] [matTabLabel]

Properties
Name Description

context: C

Contextual data to be passed in to the embedded view.

injector: Injector

The injector to use for the embedded view.

isAttached: boolean

Whether this portal is attached to a host.

origin: ElementRef

templateRef: TemplateRef<C>

The embedded template that will be used to instantiate an embedded View in the host.

viewContainerRef: ViewContainerRef

Reference to the ViewContainer into which the template will be stamped out.

Methods
attach

Attach the portal to the provided PortalOutlet. When a context is provided it will override the context property of the TemplatePortal instance.

Parameters

host

PortalOutlet

context

C = this.context

Returns
EmbeddedViewRef<C>

detach
setAttachedHost

Sets the PortalOutlet reference without performing attach(). This is used directly by the PortalOutlet when it is performing an attach() or detach().

Parameters

host

PortalOutlet

Selector: mat-tab

Exported as: matTab
Properties
Name Description
@Input('aria-label')

ariaLabel: string

Aria label for the tab.

@Input('aria-labelledby')

ariaLabelledby: string

Reference to the element that the tab is labelled by. Will be cleared if aria-label is set at the same time.

@Input()

bodyClass: string | string[]

Classes to be passed to the tab mat-tab-body container.

@Input({ transform: booleanAttribute })

disabled: boolean

whether the tab is disabled.

@Input()

labelClass: string | string[]

Classes to be passed to the tab label inside the mat-tab-header container.

@Input('label')

textLabel: string

Plain text label for the tab, used when there is no template label.

isActive: false

Whether the tab is currently active.

origin: number | null

The initial relatively index origin of the tab if it was created and selected after there was already a selected tab. Provides context of what position the tab should originate from.

position: number | null

The relatively indexed position where 0 represents the center, negative is left, and positive represents the right.

templateLabel: MatTabLabel

Content for the tab label given by <ng-template mat-tab-label>.

Material design tab-group component. Supports basic tab pairs (label + content) and includes animated ink-bar, keyboard navigation, and screen reader. See: https://material.io/design/components/tabs.html

Selector: mat-tab-group

Exported as: matTabGroup
Properties
Name Description
@Input({ alias: 'mat-align-tabs' })

alignTabs: string | null

Alignment for tabs label.

@Input()

animationDuration: string

Duration for the tab animation. Will be normalized to milliseconds if no units are set.

@Input('aria-label')

ariaLabel: string

Aria label of the inner tablist of the group.

@Input('aria-labelledby')

ariaLabelledby: string

Sets the aria-labelledby of the inner tablist of the group.

@Input()

color: ThemePalette

Theme color of the tab group. 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/tabs/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: numberAttribute })

contentTabIndex: number | null

tabindex to be set on the inner element that wraps the tab content. Can be used for improved accessibility when the tab does not have focusable elements or if it has scrollable content. The tabindex will be removed automatically for inactive tabs. Read more at https://www.w3.org/TR/wai-aria-practices/examples/tabs/tabs-2/tabs.html

@Input({ transform: booleanAttribute })

disablePagination: boolean

Whether pagination should be disabled. This can be used to avoid unnecessary layout recalculations if it's known that pagination won't be required.

@Input({ transform: booleanAttribute })

disableRipple: boolean

Whether ripples in the tab group are disabled.

@Input({ transform: booleanAttribute })

dynamicHeight: boolean

Whether the tab group should grow to the size of the active tab.

@Input({ transform: booleanAttribute })

fitInkBarToContent: boolean

Whether the ink bar should fit its width to the size of the tab label content.

@Input()

headerPosition: MatTabHeaderPosition

Position of the tab header.

@Input({ transform: booleanAttribute })

preserveContent: boolean

By default tabs remove their content from the DOM while it's off-screen. Setting this to true will keep it in the DOM which will prevent elements like iframes and videos from reloading next time it comes back into the view.

@Input({ transform: numberAttribute })

selectedIndex: number | null

The index of the active tab.

@Input({ alias: 'mat-stretch-tabs', transform: booleanAttribute })

stretchTabs: boolean

Whether tabs should be stretched to fill the header.

@Output()

animationDone: EventEmitter<void>

Event emitted when the body animation has completed

@Output()

focusChange: EventEmitter<MatTabChangeEvent>

Event emitted when focus has changed within a tab group.

@Output()

selectedIndexChange: EventEmitter<number>

Output to enable support for two-way binding on [(selectedIndex)]

@Output()

selectedTabChange: EventEmitter<MatTabChangeEvent>

Event emitted when the tab selection has changed.

@Input()
Deprecated

backgroundColor: ThemePalette

Theme color of the background of the tab group. 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/tabs/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

Methods
focusTab

Sets focus to a particular tab.

Parameters

index

number

Index of the tab to be focused.

realignInkBar

Re-aligns the ink bar to the selected tab element.

updatePagination

Recalculates the tab group's pagination dimensions.

WARNING: Calling this method can be very costly in terms of performance. It should be called as infrequently as possible from outside of the Tabs component as it causes a reflow of the page.

Navigation component matching the styles of the tab group header. Provides anchored navigation with animated ink bar.

Selector: [mat-tab-nav-bar]

Exported as: matTabNavBar, matTabNav
Properties
Name Description
@Input()

animationDuration: string

@Input()

backgroundColor: ThemePalette

Theme color of the background of the tab nav. 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/tabs/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()

color: ThemePalette

Theme color of the nav bar. 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/tabs/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 })

disablePagination: boolean

Whether pagination should be disabled. This can be used to avoid unnecessary layout recalculations if it's known that pagination won't be required.

@Input({ transform: booleanAttribute })

disableRipple: boolean

Whether the ripple effect is disabled or not.

@Input({ transform: booleanAttribute })

fitInkBarToContent: boolean

Whether the ink bar should fit its width to the size of the tab label content.

@Input({ transform: numberAttribute })

selectedIndex: number

The index of the active tab.

@Input({ alias: 'mat-stretch-tabs', transform: booleanAttribute })

stretchTabs: boolean

Whether tabs should be stretched to fill the header.

@Input()

tabPanel: MatTabNavPanel

Associated tab panel controlled by the nav bar. If not provided, then the nav bar follows the ARIA link / navigation landmark pattern. If provided, it follows the ARIA tabs design pattern.

@Output()

indexFocused: EventEmitter<number>

Event emitted when a label is focused.

@Output()

selectFocusedIndex: EventEmitter<number>

Event emitted when the option is selected.

focusIndex: number

Tracks which element has focus; used for keyboard navigation

scrollDistance: number

Sets the distance in pixels that the tab header should be transformed in the X-axis.

Methods
updateActiveLink

Notifies the component that the active link has been changed.

updatePagination

Updates the view whether pagination should be enabled or not.

WARNING: Calling this method can be very costly in terms of performance. It should be called as infrequently as possible from outside of the Tabs component as it causes a reflow of the page.

Tab panel component associated with MatTabNav.

Selector: mat-tab-nav-panel

Exported as: matTabNavPanel
Properties
Name Description
@Input()

id: string

Unique id for the tab panel.

Link inside a mat-tab-nav-bar.

Selector: [mat-tab-link] [matTabLink]

Exported as: matTabLink
Properties
Name Description
@Input({ transform: booleanAttribute })

active: boolean

Whether the link is active.

@Input({ transform: booleanAttribute })

disableRipple: boolean

Whether ripples are disabled on the tab link.

@Input({ transform: booleanAttribute })

disabled: boolean

Whether the tab link is disabled.

@Input({ transform: booleanAttribute })

fitInkBarToContent: boolean

Whether the ink bar should fit to the entire tab or just its content.

@Input()

id: string

Unique id for the tab.

elementRef: inject(ElementRef)

Methods
activateInkBar

Aligns the ink bar to the current item.

Parameters

previousIndicatorClientRect?

DOMRect

deactivateInkBar

Removes the ink bar from the current item.

focus

Focuses the tab link.

A simple change event emitted on focus or selection changes.

Properties
Name Description

index: number

Index of the currently-selected tab.

tab: MatTab

Reference to the currently-selected tab.

Object that can be used to configure the default options for the tabs module.

Properties
Name Description

alignTabs: 'start' | 'center' | 'end'

Alignment for the tabs label.

animationDuration: string

Duration for the tab animation. Must be a valid CSS value (e.g. 600ms).

contentTabIndex: number

tabindex to be set on the inner element that wraps the tab content.

disablePagination: boolean

Whether pagination should be disabled. This can be used to avoid unnecessary layout recalculations if it's known that pagination won't be required.

dynamicHeight: boolean

Whether the tab group should grow to the size of the active tab.

fitInkBarToContent: boolean

Whether the ink bar should fit its width to the size of the tab label content. This only applies to the MDC-based tabs.

preserveContent: boolean

By default tabs remove their content from the DOM while it's off-screen. Setting this to true will keep it in the DOM which will prevent elements like iframes and videos from reloading next time it comes back into the view.

stretchTabs: boolean

Whether tabs should be stretched to fill the header.

The directions that scrolling can go in when the header's tabs exceed the header width. 'After' will scroll the header towards the end of the tabs list and 'before' will scroll towards the beginning of the list.

type ScrollDirection = 'after' | 'before';

These position states are used internally as animation states for the tab body. Setting the position state to left, right, or center will transition the tab body from its current position to its respective state. If there is not current position (void, in the case of a new tab body), then there will be no transition animation to its state.

In the case of a new tab body that should immediately be centered with an animating transition, then left-origin-center or right-origin-center can be used, which will use left or right as its pseudo-prior state.

type MatTabBodyPositionState = 'left' | 'center' | 'right' | 'left-origin-center' | 'right-origin-center';

The origin state is an internally used state that is set on a new tab body indicating if it began to the left or right of the prior selected index. For example, if the selected index was set to 1, and a new tab is created and selected at index 2, then the tab body would have an origin of right because its index was greater than the prior selected index.

type MatTabBodyOriginState = 'left' | 'right';

Possible positions for the tab header.

type MatTabHeaderPosition = 'above' | 'below';

Injection token that can be used to provide the default options the tabs module.

const MAT_TABS_CONFIG: InjectionToken<MatTabsConfig>;

Injection token that can be used to reference instances of MatTabContent. It serves as alternative token to the actual MatTabContent class which could cause unnecessary retention of the class and its directive metadata.

const MAT_TAB_CONTENT: InjectionToken<MatTabContent>;

Injection token that can be used to reference instances of MatTabLabel. It serves as alternative token to the actual MatTabLabel class which could cause unnecessary retention of the class and its directive metadata.

const MAT_TAB_LABEL: InjectionToken<MatTabLabel>;

API reference for Angular Material tabs-testing

import {MatTabGroupHarness} from '@angular/material/tabs/testing';

Harness for interacting with a mat-tab-group in tests.

Properties
Name Description

static hostSelector: '.mat-mdc-tab-group'

The selector for the host element of a MatTabGroup instance.

Methods
async
getSelectedTab

Gets the selected tab of the tab group.

Returns
Promise<MatTabHarness>

async
getTabs

Gets the list of tabs in the tab group.

Parameters

filter

TabHarnessFilters = {}

Optionally filters which tabs are included.

Returns
Promise<MatTabHarness[]>

async
host

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

Returns
Promise<TestElement>

async
selectTab

Selects a tab in this tab group.

Parameters

filter

TabHarnessFilters = {}

An optional filter to apply to the child tabs. The first tab matching the filter will be selected.

Returns
Promise<void>

Promise that resolves when the action completes.

static
with

Gets a HarnessPredicate that can be used to search for a tab group with specific attributes.

Parameters

options

TabGroupHarnessFilters = {}

Options for filtering which tab group instances are considered a match.

Returns
HarnessPredicate<T>

a HarnessPredicate configured with the given options.

Harness for interacting with an Angular Material tab in tests.

Properties
Name Description

static hostSelector: '.mat-mdc-tab'

The selector for the host element of a MatTab instance.

Methods
async
getAllChildLoaders
Parameters

selector

S

Returns
Promise<HarnessLoader[]>

async
getAllHarnesses
Parameters

query

HarnessQuery<T>

Returns
Promise<T[]>

async
getAriaLabel

Gets the aria-label of the tab.

Returns
Promise<string | null>

async
getAriaLabelledby

Gets the value of the "aria-labelledby" attribute.

Returns
Promise<string | null>

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
getLabel

Gets the label of the tab.

Returns
Promise<string>

async
getRootHarnessLoader
Returns
Promise<HarnessLoader>

async
getTextContent

Gets the text content of the tab.

Returns
Promise<string>

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

Whether the tab is disabled.

Returns
Promise<boolean>

async
isSelected

Whether the tab is selected.

Returns
Promise<boolean>

async
select

Selects the given tab by clicking on the label. Tab cannot be selected if disabled.

Returns
Promise<void>

Promise that resolves when the action completes.

static
with

Gets a HarnessPredicate that can be used to search for a tab with specific attributes.

Parameters

options

TabHarnessFilters = {}

Options for filtering which tab instances are considered a match.

Returns
HarnessPredicate<T>

a HarnessPredicate configured with the given options.

Harness for interacting with a mat-tab-nav-bar in tests.

Properties
Name Description

static hostSelector: '.mat-mdc-tab-nav-bar'

The selector for the host element of a MatTabNavBar instance.

Methods
async
clickLink

Clicks a link inside the nav bar.

Parameters

filter

TabLinkHarnessFilters = {}

An optional filter to apply to the child link. The first link matching the filter will be clicked.

Returns
Promise<void>

Promise that resolves when the action completes.

async
getActiveLink

Gets the active link in the nav bar.

Returns
Promise<MatTabLinkHarness>

async
getLinks

Gets the list of links in the nav bar.

Parameters

filter

TabLinkHarnessFilters = {}

Optionally filters which links are included.

Returns
Promise<MatTabLinkHarness[]>

async
getPanel

Gets the panel associated with the nav bar.

Returns
Promise<MatTabNavPanelHarness>

async
host

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

Returns
Promise<TestElement>

static
with

Gets a HarnessPredicate that can be used to search for a tab nav bar with specific attributes.

Parameters

options

TabNavBarHarnessFilters = {}

Options for filtering which tab nav bar instances are considered a match.

Returns
HarnessPredicate<T>

a HarnessPredicate configured with the given options.

Harness for interacting with a Angular Material tab link in tests.

Properties
Name Description

static hostSelector: '.mat-mdc-tab-link'

The selector for the host element of a MatTabLink instance.

Methods
async
click

Clicks on the link.

Returns
Promise<void>

Promise that resolves when the action completes.

async
getLabel

Gets the label of the link.

Returns
Promise<string>

async
host

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

Returns
Promise<TestElement>

async
isActive

Whether the link is active.

Returns
Promise<boolean>

async
isDisabled

Whether the link is disabled.

Returns
Promise<boolean>

static
with

Gets a HarnessPredicate that can be used to search for a tab link with specific attributes.

Parameters

options

TabLinkHarnessFilters = {}

Options for filtering which tab link instances are considered a match.

Returns
HarnessPredicate<T>

a HarnessPredicate configured with the given options.

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

Properties
Name Description

label: string | RegExp

Only find instances whose label matches the given value.

selected: boolean

Only find instances whose selected state matches the given value.

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

Properties
Name Description

selectedTabLabel: string | RegExp

Only find instances whose selected tab label matches the given value.

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

Properties
Name Description

label: string | RegExp

Only find instances whose label matches the given value.

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

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