Angular Date Picker

    The Ignite UI for Angular Date Picker Component lets users pick a single date through a month-view calendar dropdown or editable input field. The picker also supports a dialog mode for selection from the calendar only, locale-aware and customizable date formatting and validation integration.

    Angular Date Picker Example

    Usage

    First Steps

    To get started with the Date Picker component, first you need to import the IgxDatePickerModule in the module that you would like to use it in, for our example we will be using the app.module.ts file.

    Note

    As the picker uses the IgxCalendarComponent, it is also dependent on the BrowserAnimationsModule and on the HammerModule for touch interactions, so they need to be added to the module as well:

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

    Display Date Picker

    To instantiate a Date Picker in its default dropdown state, use the following code:

    <igx-date-picker>
        <label igxLabel>Date</label>
    </igx-date-picker>
    

    Options

    The IgxDatePickerComponent can be bound to a date or a string.

    <igx-date-picker [value]="date"></igx-date-picker>
    
    public date = new Date(2000, 0, 1);
    

    If a string is bound to the picker, it needs to be a date-only string in the ISO 8601 format:

    <igx-date-picker [value]="'2000-01-01'"></igx-date-picker>
    

    More information about this can be found in DateTime Editor's ISO section.

    Two-way binding is possible through ngModel:

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

    As well as through the value input:

    <igx-date-picker [(value)]="date"></igx-date-picker>
    

    Additionally, formControlName can be set on the picker, to use it in a reactive form:

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

    The picker always returns a Date value, this means that If it is model bound or two-way bound to a string variable, after a new date has been chosen, it will be of type Date.

    Projecting components

    The IgxDatePickerComponent allows the projection of child components that the IgxInputGroupComponent supports (with the exception of IgxInput) - igxLabel, IgxHint, igxPrefix, igxSuffix. More detailed information about this can be found in the Label & Input topic.

    <igx-date-picker #datePicker>
        <igx-icon igxSuffix (click)="datePicker.open()">keyboard_arrow_down</igx-icon>
    </igx-date-picker>
    

    The above sample will add an additional toggle icon at the end of the input, right after the default clear icon. This will not remove the default toggle icon, though as prefixes and suffixes can be stacked one after the other.

    Customizing the toggle and clear icons

    The IgxDatePickerComponent can be configured with IgxPickerToggleComponent and IgxPickerClearComponent, these can be used to change the toggle and clear icons without having to add your own click handlers.

     <igx-date-picker>
        <label igxLabel>Select a Date</label>
        <igx-picker-toggle igxPrefix>
            <igx-icon>calendar_view_day</igx-icon>
        </igx-picker-toggle>
        <igx-picker-clear igxSuffix>
            <igx-icon>delete</igx-icon>
        </igx-picker-clear>
    </igx-date-picker>
    

    Custom action buttons

    The picker's action buttons can be modified in two ways:

    • the button's text can be changed using the todayButtonLabel) and the cancelButtonLabel input properties:

      <igx-date-picker [todayButtonLabel]="'今日'" [cancelButtonLabel]="'キャンセル'"></igx-date-picker>
      
    • the whole buttons can be templated using the igxPickerActions directive: With it you gain access to the date picker's calendar and all of its members:

      <igx-date-picker>
        <ng-template igxPickerActions let-calendar>
            <button igxButton="flat" (click)="calendar.viewDate = today">Today</button>
        </ng-template>
      </igx-date-picker>
      

    Keyboard Navigation

    Opening and closing the IgxDatePickerComponent's calendar UI with the keyboard is available only for dropdown mode and can be triggered via the key combinations below:

    Keys Description
    Space Displays the calendar pop-up and focuses it
    Alt + Displays the calendar pop-up and focuses it
    Esc Closes the calendar pop-up and focuses the input field
    Enter Closes the calendar pop-up, selecting the focused date and moves the focus to the input field
    Alt + Closes the calendar pop-up and focuses the input field

    Since the IgxDatePickerComponentuses the [IgxDateTimeEditorDirective`](date-time-editor.md) it inherits its keyboard navigation.

    Examples

    Dialog Mode

    The IgxDatePickerComponent also supports a dialog mode:

    <igx-date-picker [mode]="'dropdown'"></igx-date-picker>
    

    Display and input format

    inputFormat and displayFormat are properties which can be set to make the picker's editor follow a specified format. The inputFormat property is used when the picker is in dropdown mode and it governs the input's editable mask, as well as its placeholder (if none is set). Additionally, the inputFormat is locale based, so if none is provided, the picker will default to the one used by the browser.

    A good thing to note is that the picker will always add a leading zero on the date and month portions if they were provided in a format that does not have it, e.g. d/M/yy becomes dd/MM/yy. This applies only during editing.

    displayFormat on the other hand uses Angular's DatePipe and is used to format the picker's input when it is not focused. If no displayFormat is provided, the picker will use the inputFormat as its displayFormat.

    More information about these can be found in the IgxDateTimeEditor examples section.

    Increment and decrement

    The IgxDatePickerComponent exposes increment and decrement methods. Both of which come from the IgxDateTimeEditorDirective and can be used for incrementing and decrementing a specific DatePart of the currently set date.

    <igx-date-picker #datePicker>
        <igx-icon igxPrefix (click)="datePicker.increment(DatePart.Month, 3)">keyboard_arrow_up</igx-icon>
        <igx-icon igxPrefix (click)="datePicker.decrement(DatePart.Year. 4)">keyboard_arrow_down</igx-icon>
    </igx-date-picker>
    

    It also has as a spinDelta input property which can be used to increment or decrement a specific date part of the currently set date.

    <igx-date-picker [spinDelta]="{date: 2, month: 3, year: 4}"></igx-date-picker>
    

    In Angular Forms

    The IgxDatePickerComponent 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 minValue and maxValue properties act as form validators.

    You can see the IgxDatePickerComponent in a reactive form by visiting our Reactive Forms Integration topic.

    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.

    Calendar Specific settings

    The IgxDatePickerComponent uses the IgxCalendarComponent and you can modify some of its settings via the properties that the date picker exposes. Some of these include displayMonthsCount which allows more than one calendar to be displayed when the picker expands, weekStart which determines the starting day of the week, showWeekNumbers which shows the number for each week in the year and more.

    Internationalization

    The localization of the IgxDatePickerComponent can be controlled through its locale input. Additionally, using the igxCalendarHeader and the igxCalendarSubheader templates, provided by the IgxCalendarComponent, you can specify the look of your header and subheader. More information on how to use these templates can be found in the IgxCalendarComponent topic.

    Here is how a date picker with Japanese locale definition would look like:

    <igx-date-picker locale="ja-JP" [value]="date">
      <ng-template igxCalendarHeader let-format>
        {{ format.month.combined | titlecase }}{{format.day.combined }}{{ format.weekday.combined }}
      </ng-template>
      <ng-template igxCalendarSubheader let-format>
        <span (click)="format.yearView()">{{ format.year.combined }}</span>
        <span (click)="format.monthView()">{{ format.month.combined | titlecase }}</span>
      </ng-template>
    </igx-date-picker>
    

    Styling

    To get started with styling the date 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';
    

    The date picker uses the calendar's theme, so we have to create a new theme that extends the igx-calendar-theme and use some of its parameters to style the date picker's items:

    $custom-datepicker-theme: igx-calendar-theme(
        $header-background: #345779,
        $content-background: #fdfdfd,
        $header-text-color: #ffffff,
        $date-current-text-color: #2dabe8,
        $picker-arrow-color: #2dabe8,
        $date-selected-text-color: #fdfdfd,
        $date-current-bg-color: #fdfdfd,
        $picker-arrow-hover-color: #345779,
        $year-current-text-color: #2dabe8,
        $year-hover-text-color: #2dabe8,
        $month-current-text-color: #2dabe8,
        $month-hover-text-color: #2dabe8,
        $picker-text-color: #2dabe8,
        $picker-text-hover-color: #345779,
    );
    

    Using CSS variables

    The last step is to pass the custom date picker theme:

    @include igx-css-vars($custom-datepicker-theme);
    

    Using Theme Overrides

    In order to style components for older browsers, like Internet Explorer 11, we have to use a different approach, since it doesn't support CSS variables.

    If the component is using the Emulated ViewEncapsulation, it is necessary to penetrate this encapsulation using ::ng-deep. To prevent the custom theme to leak into other components, be sure to include the :host selector before ::ng-deep:

    :host {
       ::ng-deep {
           @include igx-calendar($custom-datepicker-theme);
       }
    }
    

    API References

    Theming Dependencies

    Additional Resources

    Our community is active and always welcoming to new ideas.