Overview for timepicker
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.
<input matInput [matTimepicker]="picker">
<mat-timepicker-toggle matIconSuffix [for]="picker"/>
<mat-timepicker #picker/>
The timepicker input and toggle can be used either on their own or as a part of a mat-form-field
:
<mat-form-field>
<mat-label>Pick a time</mat-label>
<input matInput [matTimepicker]="picker">
<mat-timepicker-toggle matIconSuffix [for]="picker"/>
<mat-timepicker #picker/>
</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.
Value: Tue Feb 04 2025 12:30:00 GMT+0000 (Coordinated Universal Time)
Touched: false
Dirty: false
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.
Value:
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.
Enter a value before 12:30 PM or after 5:30 PM to see the errors
Errors: null
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 while5h
is 5 hours. Supported short units includeh
orH
for hours,m
orM
for minutes ands
orS
for seconds. - A number with long units, for example
75 min
represents 75 minutes while1.5 hours
is an hour and a half. Supported long units includemin
orminute
orminutes
for minutes,hour
orhours
for hours andsecond
orseconds
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.
Interval examples
Custom list of options
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:
- The date locale.
- The date implementation that the timepicker accepts.
- 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.