Date Picker

The Ignite UI for Angular Date Picker component displays a month-view calendar that lets users to pick a single date in dialog mode or provides an editable input with a dropdown calendar to modify the date in dropdown mode. It supports locales and custom date formatting. The component can display today and cancel buttons in dialog mode.

Date Picker Demo

Usage

By default, the IgxDatePickerComponent allows you to pick a date from a calendar. The picker uses the IgxCalendarComponent internally as a calendar.

To get started with the Date Picker component, first you need to install Ignite UI for Angular by typing 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 our app.module.ts file:

// app.module.ts

...
import { IgxDatePickerModule } from 'igniteui-angular';

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

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

<!-- date-picker-sample.component.html -->

<igx-date-picker></igx-date-picker>

The result is as follows:

Setting date

Set a date to IgxDatePickerComponent using the value input. Just add a date:

// date-picker-sample.component.ts

public date: Date = new Date(Date.now());

Then, use the value input in the template:

<!-- date-picker-sample.component.html -->

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

And there we have it:

To create a two-way data-binding, set ngModel like this:

<!-- date-picker-sample.component.html -->

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

Adding buttons

The IgxDatePickerComponent supports 'Today' button, which selects the current day from the calendar. 'Cancel' button could be enabled as well.

To enable the buttons in a template, use the cancelButtonLabel and todayButtonLabel inputs and set the buttons text:

<!-- date-picker-sample.component.html -->

<igx-date-picker cancelButtonLabel="cancel" todayButtonLabel="today" [(ngModel)]="date"></igx-date-picker>

Setting Multi View mode

Using the monthsViewNumber input the number of displayed months in the calendar is set. To hide the days that do not belong to the current month, use the hideOutsideDays.

Here you can see the buttons:

Custom formatting

By default, the display value is formatted based on the specified locale. You could use your own formatter though. To achieve this, add a formatter function:

public date: Date = new Date(Date.now());

private dayFormatter = new Intl.DateTimeFormat("en", { weekday: "long" });
private monthFormatter = new Intl.DateTimeFormat("en", { month: "long" });

public formatter = (date: Date) => {
  return `You selected ${this.dayFormatter.format(date)}, ${date.getDate()} ${this.monthFormatter.format(date)}, ${date.getFullYear()}`;
}

And then use the formatter input of the IgxDatePickerComponent:

<!-- date-picker-sample.component.html -->

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

Here is the formatted date:

By default, the date picker is displayed in read-only dialog mode. To change it to editable dropdown mode, set the mode input to dropdown.

<!-- date-picker-sample.component.html -->

<igx-date-picker mode="dropdown"></igx-date-picker>

You can further customize the drop-down date picker, configuring the following inputs:

Input Type Description
format string Configures the date display format. Accepts formats containing valid symbols and combinations that can be applied on Angular Date Pipe. For more information, check DatePipe documentation. The following pre-defined format options are supported as well - shortDate, mediumDate, longDate and fullDate.
mask string Configures the date editor mask. Accepts combinations of the numeric representations of the d, M and y symbols and arbitrary separators - for example dd-MM-y. The editor doesn't accept the literal representation of MMM, MMMM and MMMMM. Valid masks for the day part are: d and dd, for the month part - M and MM and for the year part - y, yy and yyyy.
isSpinLoop boolean Configures the continuous spin loop when using the UP and DOWN arrow keys in the editor. If set to false, date part spinning stops when min/max date/month is reached. By default, the spin loop is infinite.
locale string When setting the locale property in editable drop-down date picker, have in mind that only the en-US locale data comes with Angular. To localize dates in another language, you must import the corresponding locale data. See the I18n guide for more information.

Note: If both formatter and format inputs are set, the drop-down date picker ignores the formatter input.

The editable drop-down date picker provides the following outputs to handle the input of disabled and invalid dates:

Output Arguments Description
onDisabledDate IDatePickerDisabledDateEventArgs Fires when the user types/spins a disabled date in the date picker editor.
onValidationFailed IDatePickerValidationFailedEventArgs Fires when the user types/spins invalid date in the date picker editor.
Keyboard Navigation
  • To open the date picker drop-down:
    • SPACE key
    • ALT + DOWN keys
  • To close the date picker drop-down:
    • ESC key
    • ALT + UP keys
  • To increment a date part:
    • Focus on a date part + UP key
  • To decrement a date part:
    • Focus on a date part + DOWN key

Templating Dialog Mode Date Picker

The Date Picker's input group look can be customized. To do that, we need to decorate the nested ng-template inside the date picker with IgxDatePickerTemplate directive. The ng-template context exposes the following members:

Members Description
openDialog Method that can be used to open the date picker dialog
disabled Controls date picker disabled state
disabledDates Contains disabled dates
displayData Contains the formatted value when date picker is in dialog mode
format Contains display format when date picker is in dropdown mode
isSpinLoop Controls continuous spin loop when date picker is in dropdown mode
label Contains the input label text
labelVisibility Controls the input label text visibility
locale Contains the locale used for formatting and displaying the dates
mask Contains the mask when date picker is in editable dropdown mode
mode Contains the date picker mode
specialDates Contains special dates
value Contains the real value
monthsViewNumber Sets the number of months displayed
hideOutsideDays Hide the days that do not belong to the current month

You could use those by declaring a variables in the ng-template element.

In the following example we modify the default label "Date" and add a second icon as suffix. Below the input group, a label is set to display the real date picker value:

<igx-date-picker [value]="date">
    <ng-template igxDatePickerTemplate let-openDialog="openDialog" let-value="value" let-displayData="displayData">
        <igx-input-group (click)="openDialog()">
            <igx-prefix>
                <igx-icon>favorite</igx-icon>
            </igx-prefix>
            <label igxLabel>My Custom Date<</label>
            <input igxInput [value]="displayData" />
            <igx-suffix>
                <igx-icon>today</igx-icon>
            </igx-suffix>
        </igx-input-group>
        <label>{{value}}</label>
    </ng-template>
</igx-date-picker>

public date: Date = new Date(Date.now());

Here is the retemplated input group:

Templating Dropdown Mode Date Picker

All the information mentioned in the Templating Dialog Mode Date Picker section can be applied when re-templating a dropdown date picker. The only requirement is that an HTML element should be passed to the openDialog(target), and that element will be used as a positioning target for the drop down that is being spawned.

Custom button action

The IgxDatePickerComponent supports predefined 'Today' and ‘Cancel’ buttons, but custom actions buttons can be added as well. To do that, wrap the buttons in ng-template marked with the igxDatePickerActions directive selector.

In the example below, two custom action buttons are included to switch to months and years calendar view.

<!-- sample.component.html -->
 <igx-date-picker mode="dropdown" #picker [(ngModel)]="date">
    <ng-template igxDatePickerActions>
        <div class="container action-buttons">
            <button igxButton="flat" (click)="monthsView(picker)">months view</button>
            <button igxButton="flat" (click)="yearsView(picker)">years view</button>
        </div>
    </ng-template>
</igx-date-picker>

// sample.component.ts
...
public date = new Date();
public monthsView(datePicker: IgxDatePickerComponent) {
    datePicker.calendar.activeViewYear();
}

public yearsView(datePicker: IgxDatePickerComponent) {
    datePicker.calendar.activeViewDecade();
}
...

The result is as follows:

Internationalization

The IgxDatePickerComponent supports locales. You can set them using the locale input. Using the IgxCalendarComponent templates for header (igxCalendarHeader) and subheader (igxCalendarSubheader), you can specify the look of your header and subheader. More information on how to use these templates you can find 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 class="date__el" (click)="format.yearView()">{{ format.year.combined }}</span>
    <span class="date__el" (click)="format.monthView()">{{ format.month.combined | titlecase }}</span>
  </ng-template>
</igx-date-picker>
Note

Keep in mind that for Internet Explorer and Edge browsers the date parts will be empty strings, because both browsers don't implement the Intl API providing this functionality. (See formatToParts)

To support those browsers we are going to use alternative template using ngIf directive:

<!-- app.component.html-->
<igx-date-picker id="date-picker" locale="ja-JP" [value]="date" #component>
    <div *ngIf="formatParts; else parseTemplate">
        <ng-template igxCalendarHeader let-format>
            {{ format.month.combined | titlecase }} {{ format.day.combined }} {{ format.weekday.combined }}
        </ng-template>
        <ng-template igxCalendarSubheader let-format>
            <span class="date__el" (click)="format.yearView()">{{ format.year.combined }}</span>
            <span class="date__el" (click)="format.monthView()">{{ format.month.combined | titlecase }}</span>
        </ng-template>
    </div>

    <!-- Parse template for browsers not supporting Intl-->
    <ng-template #parseTemplate>
        <ng-template igxCalendarHeader let-format>
            {{ getDatePart(format, component, 'month') | titlecase }} {{ getDatePart(format, component, 'day') }} {{ getDatePart(format, component, 'weekday') }}
        </ng-template>
        <ng-template igxCalendarSubheader let-format>
            <span class="date__el" (click)="format.yearView()">{{ getDatePart(format, component, 'year') }}</span>
            <span class="date__el" (click)="format.monthView()">{{ getDatePart(format, component, 'month') }}</span>
        </ng-template>
    </ng-template>
</igx-date-picker>

Note that ngIf evaluates the value of the formatParts expression to control which template to use. Let's have a look at the alternative #parseTemplate template: the expressions in the curly brackets invokes the getDatePart method that returns the evaluated value, in our case this is a formatted date part (year, weekday, month, etc.). The parameters passed to the getDatePart are necessary so that formatting is based on the IgxDatePickerComponent locale and format options:

// app.component.ts
public intlDateTimeFormat = new Intl.DateTimeFormat() as any;
public formatParts: boolean = this.intlDateTimeFormat.formatToParts;

public getDatePart(val: any, component: any, datePart: string) {
    const date = val.date as Date;
    const locale = component.locale;
    const formatOptions: Intl.DateTimeFormatOptions = {};
    formatOptions[datePart] = component.formatOptions[datePart];

    return date.toLocaleString(locale, formatOptions);

    // instead of toLocaleString we can use Intl.DateTimeFormat.format as well:
    // const partFormatter = new Intl.DateTimeFormat(locale, formatOptions);
    // return partFormatter.format(date);
}

The result is as follows:

API References

Additional Resources

Our community is active and always welcoming to new ideas.