Angular Material Time Select
npm install ngx-material-time-selectbash
npm install --save moment ngx-material-time-select
`
3. Import the time select module:
`ts
...
import {MatTimeSelectModule} from 'ngx-material-time-select';
@NgModule({
...
imports: [
BrowserModule,
BrowserAnimationsModule,
MatTimeSelectModule,
MatNativeTimeModule // Or MatMomentTimeModule
]
...
})
export class MyModule { }
`
4. Include a prebuilt theme in your style.css:
`css
@import "~ngx-material-time-select/prebuilt-themes/indigo-pink.css";
`
Usage
$3
A time-select is composed of a text input and a select panel pop-up, connected via the matTimeSelect
property on the text input.
`html
`
An optional time select toggle button is available. A toggle can be added to the example above:
`html
`
This works exactly the same with an input that is part of an and the toggle
can easily be used as a prefix or suffix on the material input:
`html
`
If you want to customize the icon that is rendered inside the mat-time-select-toggle, you can do so
by using the matTimeSelectToggleIcon directive:
$3
The type of values that the time select expects depends on the type of TimeAdapter provided in your
application. When using the default TimeAdapter, the values will all be Moment.js instances.
Depending on the TimeAdapter being used, the time select may automatically deserialize certain time
formats for you as well. For example, the TimeAdapter allow
ISO 8601 strings to be passed to the time select and
automatically converted to the proper object type. This can be convenient when binding data directly
from your backend to the time select. However, the time select will not accept time strings formatted
in user format such as "1:25 PM" as this is ambiguous and will mean different things depending on
the locale of the browser running the code.
As with other types of , the time select works with @angular/forms directives such as
formGroup, formControl, ngModel, etc.
$3
The time select popup will automatically inherit the color palette (primary, accent, or warn)
from the mat-form-field it is attached to. If you would like to specify a different palette for
the popup you can do so by setting the color property on mat-time-select.
$3
There are two properties that add time validation to the time select input. The min and max
properties.
Each validation property has a different error that can be checked:
* A value that violates the min property will have a matTimeSelectMin error.
* A value that violates the max property will have a matTimeSelectMax error.
$3
The input's native (input) and (change) events will only trigger due to user interaction with
the input element; they will not fire when the user selects a time from the select panel.
Therefore, the time select input also has support for (timeInput) and (timeChange) events. These
trigger when the user interacts with either the input or the popup.
The (timeInput) event will fire whenever the value changes due to the user typing or selecting a
time from the select panel. The (timeChange) event will fire whenever the user finishes typing input
(on blur), or when the user chooses a time from the select panel.
$3
As with any standard , it is possible to disable the time select input by adding the
disabled property. By default, the and will inherit
their disabled state from the , but this can be overridden by setting the disabled
property on the time select or toggle elements. This can be useful if you want to disable text input
but allow selection via the select panel or vice-versa.
$3
The select panel can be programmatically controlled using the open and close methods on the
. It also has an opened property that reflects the status of the popup.
$3
Internationalization of the time select is configured via three aspects:
1. The time locale.
2. The date implementation that the time select accepts.
3. The display and parse formats used by the time select.
4. The message strings used in the time select's UI.
#### Setting the locale code
The time select use the same injection token of the Datepicker from @angular/material.
See documentation.
It's also possible to set the locale at runtime using the setLocale method of the TimeAdapter.
#### Choosing a date implementation and date format settings
The time select was built to be date implementation agnostic. 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 time select to work with their chosen implementation.
The easiest way to ensure this is just to import one of the pre-made modules:
|Module |Date type|Supported locales |Dependencies |Import from |
|---------------------|---------|-----------------------------------------------------------------------|----------------------------------|--------------------------|
|MatNativeTimeModule|Date |en-US |None |ngx-material-time-select|
|MatMomentTimeModule|Moment |See project|Moment.js|ngx-material-time-select|
*Please note: MatNativeTimeModule is based off of the functionality available in JavaScript's
native Date object, and is thus not suitable for many locales. One of the biggest shortcomings of
the native Date object is the inability to set the parse format. We highly recommend using the
MomentTimeAdapter or a custom TimeAdapter that works with the formatting/parsing library of your
choice.*
These modules include providers for TimeAdapter and MAT_TIME_FORMATS
`ts
@NgModule({
imports: [MatTimeSelectModule, MatNativeTimeModule],
})
export class MyApp {}
`
Because TimeAdapter is a generic class, MatTimeSelectComponent and MatTimeSelectInputDirective
also need to be made generic. When working with these classes (for example as a ViewChild) you
should include the appropriate generic type that corresponds to the TimeAdapter implementation
you are using. For example:
`ts
@Component({...})
export class MyComponent {
@ViewChild(MatTimeSelectComponent) timeSelect: MatTimeSelectComponent;
}
`
It is also possible to create your own TimeAdapter that works with any date format your app
requires. This is accomplished by subclassing TimeAdapter and providing your subclass as the
TimeAdapter implementation. You will also want to make sure that the MAT_TIME_FORMATS provided
in your app are formats that can be understood by your date implementation. See
_Customizing the parse and display formats_for more
information about MAT_TIME_FORMATS.
`ts
@NgModule({
imports: [MatTimeSelectModule],
providers: [
{provide: TimeAdapter, useClass: MyTimeAdapter},
{provide: MAT_TIME_FORMATS, useValue: MY_DATE_FORMATS},
],
})
export class MyApp {}
`
#### Customizing the parse and display formats
The MAT_TIME_FORMATS object is just a collection of formats that the time select uses when parsing
and displaying times. These formats are passed through to the TimeAdapter so you will want to make
sure that the format objects you're using are compatible with the TimeAdapter used in your app.
`ts
@NgModule({
imports: [MatTimeSelectModule],
providers: [
{provide: MAT_TIME_FORMATS, useValue: MY_TIME_FORMATS},
],
})
export class MyApp {}
`
#### Localizing labels and messages
The various text strings used by the time select are provided through MatTimeSelectIntl.
Localization of these messages can be done by providing a subclass with translated values in your
application root module.
`ts
@NgModule({
imports: [MatTimeSelectModule],
providers: [
{provide: MatTimeSelectIntl, useClass: MyIntl},
],
})
export class MyApp {}
`
$3
The MatTimeSelectInput and MatTimeSelectToggle directives add the aria-haspopup attribute to
the native input and toggle button elements respectively, and they trigger a select panel dialog with
role="dialog".
MatTimeSelectIntl includes strings that are used for aria-labels. The time select input
should have a placeholder or be given a meaningful label via aria-label, aria-labelledby or
MatTimeSelectIntl.
#### Keyboard shortcuts
The time select supports the following keyboard shortcuts:
| Shortcut | Action |
|----------------------|-------------------------------------------|
| ALT + DOWN_ARROW | Open the select panel pop-up |
| ESCAPE | Close the select panel pop-up |
$3
#### Error: MatTimeSelectComponent: No provider found for TimeAdapter/MAT_TIME_FORMATS
This error is thrown if you have not provided all of the injectables the time select needs to work.
The easiest way to resolve this is to import the MatNativeTimeModule or MatMomentTimeModule in
your application's root module. See
_Choosing a date implementation_) for
more information.
#### Error: A MatTimeSelectComponent can only be associated with a single input
This error is thrown if more than one tries to claim ownership over the same
(via the matTimeSelect attribute on the input). A time select can only be
associated with a single input.
#### Error: Attempted to open a MatTimeSelectComponent with no associated input.
This error occurs if your is not associated with any . To associate an
input with your time select, create a template reference for the time select and assign it to the
matTimeSelect attribute on the input:
`html
``