API for core

API reference for Angular Material core

import {NativeDateModule} from '@angular/material/core';

Adapts the native JS Date for use with cdk-based components that work with dates.

Properties
Name Description

localeChanges: Observable<void>

A stream that emits when the locale changes.

Deprecated

useUtcForDisplay: boolean

Methods
addCalendarDays
Parameters

date

Date

days

number

Returns
Date

addCalendarMonths
Parameters

date

Date

months

number

Returns
Date

addCalendarYears
Parameters

date

Date

years

number

Returns
Date

addSeconds
Parameters

date

Date

amount

number

Returns
Date

clampDate

Clamp the given date between min and max dates.

Parameters

date

D

The date to clamp.

min?

D

The minimum value to allow. If null or omitted no min is enforced.

max?

D

The maximum value to allow. If null or omitted no max is enforced.

Returns
D

min if date is less than min, max if date is greater than max, otherwise date.

clone
Parameters

date

Date

Returns
Date

compareDate

Compares two dates.

Parameters

first

D

The first date to compare.

second

D

The second date to compare.

Returns
number

0 if the dates are equal, a number less than 0 if the first date is earlier, a number greater than 0 if the first date is later.

compareTime

Compares the time values of two dates.

Parameters

first

D

First date to compare.

second

D

Second date to compare.

Returns
number

0 if the times are equal, a number less than 0 if the first time is earlier, a number greater than 0 if the first time is later.

createDate
Parameters

year

number

month

number

date

number

Returns
Date

deserialize

Returns the given value if given a valid Date or null. Deserializes valid ISO 8601 strings (https://www.ietf.org/rfc/rfc3339.txt) into valid Dates and empty string into null. Returns an invalid date for all other values.

Parameters

value

any

Returns
Date | null

format
Parameters

date

Date

displayFormat

Object

Returns
string

getDate
Parameters

date

Date

Returns
number

getDateNames
Returns
string[]

getDayOfWeek
Parameters

date

Date

Returns
number

getDayOfWeekNames
Parameters

style

"long" | "short" | "narrow"

Returns
string[]

getFirstDayOfWeek
Returns
number

getHours
Parameters

date

Date

Returns
number

getMinutes
Parameters

date

Date

Returns
number

getMonth
Parameters

date

Date

Returns
number

getMonthNames
Parameters

style

"long" | "short" | "narrow"

Returns
string[]

getNumDaysInMonth
Parameters

date

Date

Returns
number

getSeconds
Parameters

date

Date

Returns
number

getValidDateOrNull

Given a potential date object, returns that same date object if it is a valid date, or null if it's not a valid date.

Parameters

obj

unknown

The object to check.

Returns
D | null

A date or null.

getYear
Parameters

date

Date

Returns
number

getYearName
Parameters

date

Date

Returns
string

invalid
Returns
Date

isDateInstance
Parameters

obj

any

isValid
Parameters

date

Date

parse
Parameters

value

any

parseFormat?

any

Returns
Date | null

parseTime
Parameters

userValue

any

parseFormat?

any

Returns
Date | null

sameDate

Checks if two dates are equal.

Parameters

first

D

The first date to check.

second

D

The second date to check.

Returns
boolean

Whether the two dates are equal. Null dates are considered equal to other null dates.

sameTime

Checks if the times of two dates are equal.

Parameters

first

D

The first date to check.

second

D

The second date to check.

Returns
boolean

Whether the times of the two dates are equal. Null dates are considered equal to other null dates.

setLocale

Sets the locale used for all dates.

Parameters

locale

L

The new locale.

setTime
Parameters

target

Date

hours

number

minutes

number

seconds

number

Returns
Date

toIso8601
Parameters

date

Date

Returns
string

today
Returns
Date

Error state matcher that matches when a control is invalid and dirty.

Methods
isErrorState
Parameters

control

AbstractControl<any, any>

form

FormGroupDirective | NgForm

Returns
boolean

Provider that defines how form controls behave with regards to displaying error messages.

Methods
isErrorState
Parameters

control

AbstractControl<any, any>

form

FormGroupDirective | NgForm

Returns
boolean

Single option inside of a <mat-select> element.

Selector: mat-option

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

disabled: boolean

Whether the option is disabled.

@Input()

id: string

The unique ID of the option.

@Input()

value: T

The form value of the option.

@Output()

onSelectionChange: EventEmitter<MatOptionSelectionChange<T>>

Event emitted when the option is selected or deselected.

active: boolean

Whether or not the option is currently active and ready to be selected. An active option displays styles as if it is focused, but the focus is actually retained somewhere else. This comes in handy for components like autocomplete where focus must remain on the input.

disableRipple: boolean

Whether ripples for the option are disabled.

group: inject<MatOptgroup>(MAT_OPTGROUP, { optional: true })

hideSingleSelectionIndicator: boolean

Whether to display checkmark for single-selection.

multiple:

Whether the wrapping component is in multiple selection mode.

selected: boolean

Whether or not the option is currently selected.

viewValue: string

The displayed value of the option. It is necessary to show the selected option in the select's trigger.

Methods
deselect

Deselects the option.

Parameters

emitEvent

boolean = true

focus

Sets focus onto this option.

Parameters

_origin?

FocusOrigin

options?

FocusOptions

getLabel

Gets the label to be used when determining whether the option should be focused.

Returns
string

select

Selects the option.

Parameters

emitEvent

boolean = true

setActiveStyles

This method sets display styles on the option to make it appear active. This is used by the ActiveDescendantKeyManager so key events will display the proper options as active on arrow key events.

setInactiveStyles

This method removes display styles on the option that made it appear active. This is used by the ActiveDescendantKeyManager so key events will display the proper options as active on arrow key events.

Component that is used to group instances of mat-option.

Selector: mat-optgroup

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

disabled: boolean

whether the option group is disabled.

@Input()

label: string

Label for the option group.

Shared directive to count lines inside a text area, such as a list item. Line elements can be extracted with a @ContentChildren(MatLine) query, then counted by checking the query list's length.

Selector: [mat-line] [matLine]

Adapts type D to be usable as a date by cdk-based components that work with dates.

Properties
Name Description

locale: L

The locale to use for all dates.

localeChanges: Observable<void>

A stream that emits when the locale changes.

Methods
addCalendarDays

Adds the given number of days to the date. Days are counted as if moving one cell on the calendar for each day.

Parameters

date

D

The date to add days to.

days

number

The number of days to add (may be negative).

Returns
D

A new date equal to the given one with the specified number of days added.

addCalendarMonths

Adds the given number of months to the date. Months are counted as if flipping a page on the calendar for each month and then finding the closest date in the new month. For example when adding 1 month to Jan 31, 2017, the resulting date will be Feb 28, 2017.

Parameters

date

D

The date to add months to.

months

number

The number of months to add (may be negative).

Returns
D

A new date equal to the given one with the specified number of months added.

addCalendarYears

Adds the given number of years to the date. Years are counted as if flipping 12 pages on the calendar for each year and then finding the closest date in the new month. For example when adding 1 year to Feb 29, 2016, the resulting date will be Feb 28, 2017.

Parameters

date

D

The date to add years to.

years

number

The number of years to add (may be negative).

Returns
D

A new date equal to the given one with the specified number of years added.

addSeconds

Adds an amount of seconds to the specified date.

Parameters

date

D

Date to which to add the seconds.

amount

number

Amount of seconds to add to the date.

Returns
D

clampDate

Clamp the given date between min and max dates.

Parameters

date

D

The date to clamp.

min?

D

The minimum value to allow. If null or omitted no min is enforced.

max?

D

The maximum value to allow. If null or omitted no max is enforced.

Returns
D

min if date is less than min, max if date is greater than max, otherwise date.

clone

Clones the given date.

Parameters

date

D

The date to clone

Returns
D

A new date equal to the given date.

compareDate

Compares two dates.

Parameters

first

D

The first date to compare.

second

D

The second date to compare.

Returns
number

0 if the dates are equal, a number less than 0 if the first date is earlier, a number greater than 0 if the first date is later.

compareTime

Compares the time values of two dates.

Parameters

first

D

First date to compare.

second

D

Second date to compare.

Returns
number

0 if the times are equal, a number less than 0 if the first time is earlier, a number greater than 0 if the first time is later.

createDate

Creates a date with the given year, month, and date. Does not allow over/under-flow of the month and date.

Parameters

year

number

The full year of the date. (e.g. 89 means the year 89, not the year 1989).

month

number

The month of the date (0-indexed, 0 = January). Must be an integer 0 - 11.

date

number

The date of month of the date. Must be an integer 1 - length of the given month.

Returns
D

The new date, or null if invalid.

deserialize

Attempts to deserialize a value to a valid date object. This is different from parsing in that deserialize should only accept non-ambiguous, locale-independent formats (e.g. a ISO 8601 string). The default implementation does not allow any deserialization, it simply checks that the given value is already a valid date object or null. The <mat-datepicker> will call this method on all of its @Input() properties that accept dates. It is therefore possible to support passing values from your backend directly to these properties by overriding this method to also deserialize the format used by your backend.

Parameters

value

any

The value to be deserialized into a date object.

Returns
D | null

The deserialized date object, either a valid date, null if the value can be deserialized into a null date (e.g. the empty string), or an invalid date.

format

Formats a date as a string according to the given format.

Parameters

date

D

The value to format.

displayFormat

any

The format to use to display the date as a string.

Returns
string

The formatted date string.

getDate

Gets the date of the month component of the given date.

Parameters

date

D

The date to extract the date of the month from.

Returns
number

The month component (1-indexed, 1 = first of month).

getDateNames

Gets a list of names for the dates of the month.

Returns
string[]

An ordered list of all date of the month names, starting with '1'.

getDayOfWeek

Gets the day of the week component of the given date.

Parameters

date

D

The date to extract the day of the week from.

Returns
number

The month component (0-indexed, 0 = Sunday).

getDayOfWeekNames

Gets a list of names for the days of the week.

Parameters

style

"long" | "short" | "narrow"

The naming style (e.g. long = 'Sunday', short = 'Sun', narrow = 'S').

Returns
string[]

An ordered list of all weekday names, starting with Sunday.

getFirstDayOfWeek

Gets the first day of the week.

Returns
number

The first day of the week (0-indexed, 0 = Sunday).

getHours

Gets the hours component of the given date.

Parameters

date

D

The date to extract the hours from.

Returns
number

getMinutes

Gets the minutes component of the given date.

Parameters

date

D

The date to extract the minutes from.

Returns
number

getMonth

Gets the month component of the given date.

Parameters

date

D

The date to extract the month from.

Returns
number

The month component (0-indexed, 0 = January).

getMonthNames

Gets a list of names for the months.

Parameters

style

"long" | "short" | "narrow"

The naming style (e.g. long = 'January', short = 'Jan', narrow = 'J').

Returns
string[]

An ordered list of all month names, starting with January.

getNumDaysInMonth

Gets the number of days in the month of the given date.

Parameters

date

D

The date whose month should be checked.

Returns
number

The number of days in the month of the given date.

getSeconds

Gets the seconds component of the given date.

Parameters

date

D

The date to extract the seconds from.

Returns
number

getValidDateOrNull

Given a potential date object, returns that same date object if it is a valid date, or null if it's not a valid date.

Parameters

obj

unknown

The object to check.

Returns
D | null

A date or null.

getYear

Gets the year component of the given date.

Parameters

date

D

The date to extract the year from.

Returns
number

The year component.

getYearName

Gets the name for the year of the given date.

Parameters

date

D

The date to get the year name for.

Returns
string

The name of the given year (e.g. '2017').

invalid

Gets date instance that is not valid.

Returns
D

An invalid date.

isDateInstance

Checks whether the given object is considered a date instance by this DateAdapter.

Parameters

obj

any

The object to check

Returns
boolean

Whether the object is a date instance.

isValid

Checks whether the given date is valid.

Parameters

date

D

The date to check.

Returns
boolean

Whether the date is valid.

parse

Parses a date from a user-provided value.

Parameters

value

any

The value to parse.

parseFormat

any

The expected format of the value being parsed (type is implementation-dependent).

Returns
D | null

The parsed date.

parseTime

Parses a date with a specific time from a user-provided value.

Parameters

value

any

The value to parse.

parseFormat

any

The expected format of the value being parsed (type is implementation-dependent).

Returns
D | null

sameDate

Checks if two dates are equal.

Parameters

first

D

The first date to check.

second

D

The second date to check.

Returns
boolean

Whether the two dates are equal. Null dates are considered equal to other null dates.

sameTime

Checks if the times of two dates are equal.

Parameters

first

D

The first date to check.

second

D

The second date to check.

Returns
boolean

Whether the times of the two dates are equal. Null dates are considered equal to other null dates.

setLocale

Sets the locale used for all dates.

Parameters

locale

L

The new locale.

setTime

Sets the time of one date to the time of another.

Parameters

target

D

Date whose time will be set.

hours

number

New hours to set on the date object.

minutes

number

New minutes to set on the date object.

seconds

number

New seconds to set on the date object.

Returns
D

toIso8601

Gets the RFC 3339 compatible string (https://tools.ietf.org/html/rfc3339) for the given date. This method is used to generate date strings that are compatible with native HTML attributes such as the min or max attribute of an <input>.

Parameters

date

D

The date to get the ISO date string for.

Returns
string

The ISO date string date string.

today

Gets today's date.

Returns
D

Today's date.

Event object emitted by MatOption when selected or deselected.

Properties
Name Description

isUserInput: false

Whether the change in the option's value was a result of a user action.

source: MatOption<T>

Reference to the option that emitted the event.

Object that can be used to configure the sanity checks granularly.

Deprecated
Properties
Name Description

doctype: boolean

theme: boolean

version: boolean

provideNativeDateAdapter
Parameters

formats

MatDateFormats = MAT_NATIVE_DATE_FORMATS

Returns
Provider[]

Deprecated

Possible sanity checks that can be enabled. If set to true/false, all checks will be enabled/disabled.

type SanityChecks = boolean | GranularSanityChecks;

Possible color palette values.

type ThemePalette = 'primary' | 'accent' | 'warn' | undefined;
type MatDateFormats = {
    parse: {
        dateInput: any;
        timeInput?: any;
    };
    display: {
        dateInput: any;
        monthLabel?: any;
        monthYearLabel: any;
        dateA11yLabel: any;
        monthYearA11yLabel: any;
        timeInput?: any;
        timeOptionLabel?: any;
    };
};

Current version of Angular Material.

const VERSION: Version;
Deprecated

Injection token that configures whether the Material sanity checks are enabled.

const MATERIAL_SANITY_CHECKS: InjectionToken<SanityChecks>;

InjectionToken for datepicker that can be used to override default locale code.

const MAT_DATE_LOCALE: InjectionToken<{}>;
const MAT_DATE_FORMATS: InjectionToken<MatDateFormats>;
const MAT_NATIVE_DATE_FORMATS: MatDateFormats;

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

const MAT_OPTGROUP: InjectionToken<MatOptgroup>;

Injection token used to provide the parent component to options.

const MAT_OPTION_PARENT_COMPONENT: InjectionToken<MatOptionParentComponent>;

API reference for Angular Material core-testing

import {MatOptionHarness} from '@angular/material/core/testing';

Harness for interacting with a mat-option in tests.

Properties
Name Description

static hostSelector: '.mat-mdc-option'

Selector used to locate option instances.

Methods
async
click

Clicks the option.

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 the option's label text.

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
isActive

Gets whether the option is active.

Returns
Promise<boolean>

async
isDisabled

Gets whether the option is disabled.

Returns
Promise<boolean>

async
isMultiple

Gets whether the option is in multiple selection mode.

Returns
Promise<boolean>

async
isSelected

Gets whether the option is selected.

Returns
Promise<boolean>

static
with

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

Parameters

options

OptionHarnessFilters = {}

Options for filtering which option instances are considered a match.

Returns
HarnessPredicate<T>

a HarnessPredicate configured with the given options.

Harness for interacting with a mat-optgroup in tests.

Properties
Name Description

static hostSelector: '.mat-mdc-optgroup'

Selector used to locate option group instances.

Methods
async
getLabelText

Gets the option group's label text.

Returns
Promise<string>

async
getOptions

Gets the options that are inside the group.

Parameters

filter

OptionHarnessFilters = {}

Optionally filters which options are included.

Returns
Promise<MatOptionHarness[]>

async
host

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

Returns
Promise<TestElement>

async
isDisabled

Gets whether the option group is disabled.

Returns
Promise<boolean>

static
with

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

Parameters

options

OptgroupHarnessFilters = {}

Options for filtering which option instances are considered a match.

Returns
HarnessPredicate<T>

a HarnessPredicate configured with the given options.

Properties
Name Description

isSelected: boolean

text: string | RegExp

Properties
Name Description

labelText: string | RegExp