Time Picker

    The time picker component allows users to input or select time portions from a dropdown/dialog with spinners, which is then mirrored in the input field. In dropdown mode, which is the default one, the input field is editable and users can also edit selected time.

    Angular Time Picker Example

    Usage

    The first step is to import the IgxTimePickerModule in the app.module.ts file.

    Note

    The IgxTimePicker is also dependent on both the BrowserAnimationsModule and HammerModule for touch interactions. They need to be added to the AppModule as well.

    // app.module.ts
    
    ...
    import { HammerModule } from "@angular/platform-browser";
    import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
    import { IgxTimePickerModule } from 'igniteui-angular';
    
    @NgModule({
        ...
        imports: [..., BrowserAnimationsModule, HammerModule, IgxTimePickerModule],
        ...
    })
    export class AppModule {}
    

    Default

    To add the time picker in a template, use the following code:

    <!--meeting.component.html-->
    <igx-time-picker></igx-time-picker>
    

    The output should be the same as the one in the demo.

    Binding

    The time picker can be bound to either a Date object or time-only string value in ISO 8601 format by setting the value property or ngModel.

    First create a time string in ISO 8601 format:

    public time = '09:15:30';
    

    Then use the ngModel to create a two-way data-binding:

    <igx-time-picker [(ngModel)]="time"></igx-time-picker>
    

    or set value input in the template:

    <igx-time-picker [value]="time"></igx-time-picker>
    

    To use it in a reactive form you need to set a formControlName on the picker

    <form [formGroup]="form">
        <igx-time-picker formControlName="timePicker"></igx-time-picker>
    </form>
    
    export class SampleFormComponent {
        // ...
        public form: FormGroup;
        constructor(private fb: FormBuilder) {
            this.form = this.fb.group({
                timePicker: ['', Validators.required]
            });
        }
    }
    

    Projecting components

    The time picker component allows projecting child components - the same as in the IgxInputGroupComponent: igxLabel, IgxHint, igxPrefix, igxSuffix, excluding IgxInput. More detailed information about this can be found in the Label & Input topic.

    In the default configuration, a dropdown/dialog toggle icon is shown as a prefix. It can be changed or redefined using the IgxPickerToggleComponent component. It can be decorated with either igxPrefix or igxSuffix, which will define its position - at the start of the input or at the end respectively.

    In the following example we have added a custom label and hint and changed the default toggle icon position to be displayed as a suffix:

    <igx-time-picker [(ngModel)]="date" mode="dialog" [inputFormat]="'hh:mm'">
        <label igxLabel>Home Time </label>
        <igx-picker-toggle igxSuffix>
            <igx-icon>home</igx-icon>
        </igx-picker-toggle>
        <igx-hint>{{date.toLocaleString()}}</igx-hint>
    </igx-time-picker>
    
    public date: Date = new Date();
    

    And here's our templated time picker:

    Custom action buttons

    The IgxTimePickerComponent supports action button customization. To achieve that, wrap the buttons in ng-template marked with the igxPickerActions directive selector.

    In the example below, custom action buttons are added for 'CANCEL', 'DONE' and 'NOW' actions.

    <!-- sample.component.html -->
    
    <igx-time-picker #picker format="hh:mm" mode="dropdown">
        <ng-template igxTimePickerActions>
            <div class="container action-buttons">
                <button igxButton="flat" (click)="picker.cancelButtonClick()">cancel</button>
                <button igxButton="flat" (click)="picker.okButtonClick()">done</button>
                <button igxButton="flat" (click)="selectNow(picker)">now</button>
            </div>
        </ng-template>
    </igx-time-picker>
    
    // sample.component.ts
    ...
    public selectNow(timePicker: IgxTimePickerComponent) {
        timePicker.value = new Date();
        timePicker.close();
    }
    ...
    

    And there we have it, a re-templated time picker with dropdown, custom actions and two-way binding support:

    Keyboard Navigation

    • Users can navigate the component's time portions via the keyboard Up and Down arrow keys or by scrolling in the input field and in the dropdown/dialog. Navigation in the input is possible regardless of the minValue or maxValue, while navigation in the dropdown/dialog will be restricted within the minValue and maxValue range.
    • The time picker dropdown can be opened either by toggle icon click, Space key or Alt + Down keys press. In dialog mode this can be done by input click.
    • Enter key press or mouse click outside the dropdown/dialog applies the selection and closes the dropdown/dialog.
    • Pressing the Escape key cancels the selection and closes the dropdown/dialog.
    • When entered a new value while dropdown is closed, click outside of the time picker or press Tab to move the focus so that the value is accepted.

    Examples

    Dialog Mode

    The default time picker mode is editable dropdown mode. To change the time picker mode to read-only dialog mode, set the mode input to dialog:

    // timePickerDropdown.component.ts
    
    import { PickerInteractionMode } from 'igniteui-angular';
    ...
    public mode = PickerInteractionMode.Dialog;
    
    <!--timePickerDropdown.component.html-->
    <igx-time-picker [mode]="mode"></igx-time-picker>
    

    or just change the mode in the time picker like this:

    <!--timePickerDropdown.component.html-->
    <igx-time-picker mode="dialog"></igx-time-picker>
    

    In dialog mode, the dialog header displays the currently selected time in the picker's input format. You can change the header position by setting the headerOrientation property.

    When the minValue and maxValue are set the dialog displays the time within that range only. See the Min max value example below, for more details.

    Display and input format

    The time picker component supports different display and input formats.

    The display format is the format of the value when in edit mode and can be one of the listed Angular DatePipe formats. This allows it to support predefined format options, such as shortTime and longTime.

    The input format is the format of the value when not in edit mode and the format, in which the time portions are displayed in the dropdown/dialog. The inputFormat property accepts a constructed format string using characters supported by the DatePipe, e.g. hh:mm:ss, but doesn't support predefined format options, such as shortTime and longTime. If the inputFormat property is not defined, it defaults to hh:mm tt.

    <igx-time-picker
    [(ngModel)]="time"
    [inputFormat]="`hh:mm:ss`"
    [displayFormat]="`shortTime`">
    </igx-time-picker>
    

    Note: The IgxTimePicker now supports IME input. When composition ends, the control converts the wide-character numbers to ASCII characters.

    Increment and decrement

    The time picker exposes public increment and decrement methods, which accept two optional parametars: the DatePart to be modified and the delta by which it will be changed. If not specified the DatePart defaults to Hours and the delta defaults to itemsDelta.

    You can find a sample that illustrates the use of both methods at Date Time Editor Directive.

    Forms and Validation

    The time picker component supports all directives from the core FormsModule NgModel and ReactiveFormsModule (FormControl, FormGroup, etc.). This also includes the Forms Validators functions. In addition, the component's min and max values also act as form validators.

    The Reactive Forms Integration sample demonstrates how to use the igxTimePicker in Reactive Forms.

    Min max value

    You can specify minValue and maxValue to restrict the user input, in which case the dropdown/dialog will display the time within that range only. In dropdown mode however, it is still possible for the user to type in an invalid time. You can handle the validationFailed event in order to notify the user if that happens.

    Note

    The min/max values should be a Date object or a time-only string in the ISO 8601 format:

    // app.module.ts
    
    ...
    import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
    import { IgxTimePickerModule, IgxToastModule } from 'igniteui-angular';
    
    @NgModule({
        ...
        imports: [..., BrowserAnimationsModule, IgxTimePickerModule, IgxToastModule],
        ...
    })
    export class AppModule {}
    
    // app.component.ts
    
    public time = '10:00:00';
    public min = '09:15:30';
    public max = '18:15:30';
    
    @ViewChild("toast", { static: true })
    private toast;
    
    public onValidationFailed() {
        this.toast.open();
    }
    
    <igx-time-picker
        [(ngModel)]="time"
        [itemsDelta]="{hours:2, minutes:5}"
        [inputFormat]="'hh:mm:ss tt'"
        [headerOrientation]="true"
        [minValue]="min"
        [maxValue]="max"
        (onValidationFailed)="onValidationFailed()">
        <label igxLabel>Meeting Start</label>
    </igx-time-picker>
    
    <igx-toast #toast message="Value must be between 09:15:30 AM and 06:15:30 PM"></igx-toast>
    

    The dropdown displays values within the min/max range (09:15:30 AM~06:15:30 PM) based on the items delta. A toast is added to show a message when an invalid time has been typed in.

    Note

    The displayed values for each time portion in the dropdown/dialog are calculated based on the items delta always starting from zero. If the minValue and maxValue does not match the items delta, the displayed values will start/end from the next/last possible value that matches the threshold.

    And there we have it:

    Using date and time picker together

    In some cases when the IgxDatePicker and the IgxTimePicker are used together, we might need them to be bound to one and the same Date object value.

    To achieve that in template driven forms, use the ngModel to bind both components to the same Date object.

    In reactive forms, we can handle the valueChange event of each component and update the value of the other.

    Styling

    To get started with styling the time picker, we need to import the index file, where all the theme functions and component mixins live:

    @import '~igniteui-angular/lib/core/styles/themes/index';
    

    Following the simplest approach, we create a new theme that extends the igx-time-picker-theme and accepts parameters that style the time picker.

    $my-time-picker-theme: igx-time-picker-theme(
      $text-color: #E4C8A5,
      $hover-text-color: #ECAA53,
      $selected-text-color: #ECAA53,
      $header-background: #ECAA53,
      $header-hour-text-color: #011627,
      $header-time-period-color: #011627,
      $background-color: #011627
    );
    
    Note

    In order to style any additional components that are used as part of the time picker window's content (such as the IgxButton), an additional theme should be created that is specific to the respective component and is placed under the dialog window's scope only (so it does not affect the rest of the application).

    Since the time picker window uses the IgxOverlayService, in order for our custom theme to reach down the time picker window that we want to style, we will provide a specific outlet where the dialog window will be placed in the DOM when it is visible.

    The items in our time picker are not descendants of our component host - they are currently being displayed in the default overlay outlet, at the end of the document body. Changing this is done by making use of the outlet property in the overlaySettings. The outlet controls where the overlay container should be rendered.

    Here, we can pass a reference to the element where we'd like our container to be:

    <igx-time-picker #picker [overlaySettings]="{ outlet: element }">
    </igx-time-picker>
    
    export class TimepickerStylingComponent {
        ...
        constructor(public element: ElementRef) {
        }
    }
    

    Now, the time picker's items are properly rendered inside of our component's host, which means that our custom theme will take effect:

    Note

    In order to learn more about the various options for providing themes to elements that are shown by using the IgxOverlayService, you can take a look at the Overlay styling topic.

    Including Themes

    The last step is to include the component theme in our application.

    If $legacy-support is set to true, include the theme like that:

     @include igx-time-picker($my-time-picker-theme);
    
    Note

    If the component is using an Emulated ViewEncapsulation, it is necessary to penetrate this encapsulation using ::ng-deep

    :host {
         ::ng-deep {
            @include igx-time-picker($my-time-picker-theme);
        }
    }
    

    If $legacy-support is set to false(default), include the component css variables like that:

    @include igx-css-vars($my-time-picker-theme);
    
    Note

    If the component is using an Emulated ViewEncapsulation, you still have to use :host because you need a global selector in order to override the variables.

    :host {
        @include igx-css-vars($my-time-picker-theme);
    }
    

    Demo

    API References

    Theming Dependencies

    Additional Resources

    Our community is active and always welcoming to new ideas.