Angular Datepicker Component Overview

Angular DatePicker is a feature rich component used for entering a date through manual text input or choosing date values from a calendar dialog that pops up. Lightweight and simple to use, the DatePicker in Angular lets users to navigate to a desired date with several view options – month, year, decade. There are the usual min, max, and required properties to add validation.

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

Angular Datepicker Example

Below you can see a sample that demonstrates how the Angular DatePicker works when users are enabled to pick a date through a manual text input and click on the calendar icon on the left to navigate to it. See how to render it.

Getting Started with Ignite UI for Angular Datepicker

To get started with the Ignite UI for Angular Datepicker component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command:

ng add igniteui-angular

For a complete introduction to the Ignite UI for Angular, read the getting started topic.

The next step is to import the IgxDatePickerModule in your app.module.ts file.

Note

As the picker uses the IgxCalendarComponent, it is also dependent on the BrowserAnimationsModule and optionally 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';
// import { IgxDatePickerModule } from '@infragistics/igniteui-angular'; for licensed package

@NgModule({
    ...
    imports: [..., IgxDatePickerModule, BrowserAnimationsModule, HammerModule],
    ...
})
export class AppModule {}

Alternatively, as of 16.0.0 you can import the IgxDatePickerComponent as a standalone dependency, or use the IGX_DATE_PICKER_DIRECTIVES token to import the component and all of its supporting components and directives.

// home.component.ts

import { HammerModule } from '@angular/platform-browser';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
import { IGX_DATE_PICKER_DIRECTIVES } from 'igniteui-angular';
// import { IGX_DATE_PICKER_DIRECTIVES } from '@infragistics/igniteui-angular'; for licensed package

@Component({
    selector: 'app-home',
    template: `
    <igx-date-picker>
        <label igxLabel>Date</label>
    </igx-date-picker>
    `,
    styleUrls: ['home.component.scss'],
    standalone: true,
    imports: [BrowserAnimationsModule, HammerModule, IGX_DATE_PICKER_DIRECTIVES]
    /* or imports: [BrowserAnimationsModule, HammerModule, IgxDatePickerComponent, IgxLabelDirective] */
})
export class HomeComponent {}

Now that you have the Ignite UI for Angular Datepicker module or directives imported, you can start using the igx-date-picker component.

Using the Angular Datepicker Component

Display Datepicker

To instantiate a Datepicker 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, igx-hint / IgxHint, igx-prefix / igxPrefix, igx-suffix / 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 snippet 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>

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 IgxDatePickerComponent uses the IgxDateTimeEditorDirective it inherits its keyboard navigation.

Examples

Dialog Mode

The IgxDatePickerComponent also supports a dialog mode:

<igx-date-picker [mode]="'dialog'"></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 the Angular DatePicker Component in Ignite UI 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.

Note

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

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 an Angular DatePicker 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:

@use "igniteui-angular/theming" as *;

// IMPORTANT: Prior to Ignite UI for Angular version 13 use:
// @import '~igniteui-angular/lib/core/styles/themes/index';

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

$custom-datepicker-theme: 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 Angular DatePicker theme:

@include 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 calendar($custom-datepicker-theme);
   }
}

API References

Theming Dependencies

Additional Resources

Our community is active and always welcoming to new ideas.

Angular Datepicker Component Overview

Angular Datepicker Example

Getting Started with Ignite UI for Angular Datepicker

Note

Using the Angular Datepicker Component

Display Datepicker

Options

Note

Projecting components

Customizing the toggle and clear icons

Custom action buttons

Keyboard Navigation

Examples

Dialog Mode

Display and input format

Note

Increment and decrement

In Angular Forms

Using date and time picker together

Calendar Specific settings

Internationalization

Styling

Using CSS variables

Using Theme Overrides

API References

Theming Dependencies

Additional Resources

Theming