sass-references/angular-material/material/timepicker/timepicker.md

The Angular Material Timepicker allows users to set the time portion of a date object either by typing it in or by selecting it from a list of pre-defined options.

Connecting a timepicker to an input

A timepicker is composed of a text input and a dropdown menu, connected through the matTimepicker binding on the input.

There is also an optional timepicker toggle button that gives the user an easy way to open the dropdown.

The timepicker input and toggle can be used either on their own or as a part of a mat-form-field:

Timepicker forms integration

The timepicker input integrates with the @angular/forms module by providing itself as a ControlValueAccessor and a Validator (see Input validation below for more information). When the user types in a new time or selects one from the dropdown, the time will be set on the date object which is the current value of the form control. If the form control doesn't have a value, the timepicker will create one with today's date and the selected time.

Integration with MatDatepicker

Material's datepicker and timepicker components can operate over the same value, allowing for a combined datetime picker to be implemented. When binding the two components to the same value, the datepicker will set the entire date object while the timepicker will only modify the time portion of it.

Input validation

The timepicker input checks that the value typed in by the user is a valid time string and whether it fits into the specified bounds.

If the user types in an invalid time string (for example abc or 24:67), the timepicker input will report the matTimepickerParse error. The string is parsed using the parseTime method of the the current date implementation.

The timepicker input also checks that the value typed in by the user fits within the minimum and maximum bounds set through the matTimepickerMin and matTimepickerMax inputs. They accept either a date object with a specific time or a time string. The inputs also control which times will be shown inside of the dropdown menu. For example, setting matTimepickerMin="12:30" and matTimepickerMax="21:25" will allow the user to only select a time between 12:30 in the afternoon and 9:25 in the evening. If the value is outside of those bounds, either a maxTimepickerMin or matTimepickerMax error will be reported to the value accessor.

Customizing the dropdown options

By default the mat-timepicker dropdown shows options at 30 minute intervals. You can customize the list of options either by setting an interval or providing a custom set of options.

The easiest way is to change the options is to pass the interval input to mat-timepicker with an interval string which will be used when generating the options. For example, <mat-timepicker interval="90m"/> will show the options at 90 minute intervals, starting from the minimum time and ending at the maximum. Valid interval strings include:

• A number which will be interpreted as minutes, e.g. interval="50" represents 50 minutes.
• A number with short units, for example 30m represents 30 minutes while 5h is 5 hours. Supported short units include h or H for hours, m or M for minutes and s or S for seconds.
• A number with long units, for example 75 min represents 75 minutes while 1.5 hours is an hour and a half. Supported long units include min or minute or minutes for minutes, hour or hours for hours and second or seconds for seconds.

Furthermore, the default interval can be controlled for the entire application using the MAT_TIMEPICKER_CONFIG injection token. For example, adding the following to your providers will default all timepickers to a 90 minute interval:

import {MAT_TIMEPICKER_CONFIG} from '@angular/material/timepicker';

{
  provide: MAT_TIMEPICKER_CONFIG,
  useValue: {interval: '90 minutes'},
}

If your app requires more fine-grained control over the options, you can pass in an array of options into mat-timepicker instead. Note that the options need to match the MatTimepickerOption interface.

Customizing the toggle icon

mat-timepicker-toggle renders a clock icon by default. You can customize it by projecting in an element with the matTimepickerToggleIcon attribute into the toggle:

Internationalization

Internationalization of the timepicker uses the same date adapter as mat-datepicker. It is configured via three aspects:

1. The date locale.
2. The date implementation that the timepicker accepts.
3. The display and parse formats used by the timepicker.

Setting the locale code

By default, the MAT_DATE_LOCALE injection token will use the existing LOCALE_ID locale code from @angular/core. If you want to override it, you can provide a new value for the MAT_DATE_LOCALE token:

bootstapApplication(MyApp, {
  providers: [{provide: MAT_DATE_LOCALE, useValue: 'en-GB'}],
});

It's also possible to set the locale at runtime using the setLocale method of the DateAdapter.

Note: if you're using the provideDateFnsAdapter, you have to provide the data object for your locale to MAT_DATE_LOCALE instead of the locale code, in addition to providing a configuration compatible with date-fns to MAT_DATE_FORMATS. Locale data for date-fns can be imported from date-fns/locale.

Choosing a date implementation and format settings

The timepicker is built to be implementation-agnostic and to be interoperable with mat-datepicker. This means that it can be made to work with a variety of different date implementations. However it also means that developers need to make sure to provide the appropriate pieces for the timepicker to work with their chosen implementation.

The easiest way to ensure this is to import one of the provided date adapters:

provideNativeDateAdapter or MatNativeDateModule

Date type	Date
Supported locales	Locales using either AM/PM or 24-hour formatting
Dependencies	None
Import from	@angular/material/core

provideDateFnsAdapter or MatDateFnsModule (installed via ng add @angular/material-date-fns-adapter)

Date type	Date
Supported locales	See project for details
Dependencies	date-fns
Import from	@angular/material-date-fns-adapter

provideLuxonDateAdapter or MatLuxonDateModule (installed via ng add @angular/material-luxon-adapter)

Date type	DateTime
Supported locales	See project for details
Dependencies	Luxon
Import from	@angular/material-luxon-adapter

provideMomentDateAdapter or MatMomentDateModule (installed via ng add @angular/material-moment-adapter)

Date type	Moment
Supported locales	See project for details
Dependencies	Moment.js
Import from	@angular/material-moment-adapter

Note: provideNativeDateAdapter implements time parsing using a regex which means that it only supports AM/PM time (e.g. 1:45 PM) or 24-hour time (e.g. 22:45 or 22.45). As such it won't work on locales with different formatting. We recommend using one of the provided date adapters mentioned above or creating your own adapter by extending the DateAdapter class from @angular/material/core. For example, if you want to use the date-fns adapter, you can update your bootstrapApplication format to the following:

import {provideDateFnsAdapter} from '@angular/material-date-fns-adapter';

bootstrapApplication(MyApp, {
  providers: [provideDateFnsAdapter()]
});

Customizing the parse and display formats

The MAT_DATE_FORMATS object is a collection of formats that the timepicker uses when parsing and displaying date objects. These formats are passed through to the DateAdapter so you will want to make sure that the format objects you're providing are compatible with the DateAdapter used in your app.

MAT_DATE_FORMATS is the same object used by mat-datepicker so it's likely already configured if your app is using the datepicker, but for the timepicker you need to ensure that the display.timeInput, display.timeOptionLabel and parse.timeInput properties are set as well.

If you want use one of the DateAdapters that ships with Angular Material, but use your own MAT_DATE_FORMATS, you can either pass the formats into the providers function, or provide the MAT_DATE_FORMATS token yourself. For example:

bootstrapApplication(MyApp, {
  providers: [provideNativeDateAdapter(MY_NATIVE_DATE_FORMATS)],
});

Accessibility

The timepicker implements the ARIA combobox interaction pattern. The timepicker input specifies role="combobox" while the content of the dropdown applies role="listbox" and the options within the dropdown apply role="option". By default the listbox is labelled from the mat-form-field it is placed in, but if you aren't using a form field or if you want to customize the label, you can do so through the ariaLabel or ariaLabelledby inputs on mat-timepicker.

Troubleshooting

Error: MatTimepicker: No provider found for DateAdapter/MAT_DATE_FORMATS

This error is thrown if you haven't provided all of the injectables the timepicker needs in order to work correctly. The easiest way to resolve this is to add provideNativeDateAdapter or provideMomentDateAdapter to your app config. See Choosing a date implementation for more information.

Error: MatTimepicker: Incomplete MAT_DATE_FORMATS has been provided

The timepicker needs the display.timeInput, display.timeOptionLabel and parse.timeInput fields in MAT_DATE_FORMATS in order to work correctly. You should update your date formats object to include include these fields. See Customizing the parse and display formats for more information.

Error: Cannot specify both the options and interval inputs at the same time

A mat-timepicker cannot specifify both the options and interval inputs at the same time. The template should be updated to remove one of them.

Error: Value of options input cannot be an empty array

The array passed into the options input of mat-timepicker cannot be empty, because the user won't have any options to choose from.

Error: A MatTimepicker can only be associated with a single input

This error is thrown if more than one <input> tries to claim ownership over the same <mat-timepicker> (via the matTimepicker attribute on the input). A timepicker can only be associated with a single input.