Angular Date Range Picker Component Overview

Angular Date Range Picker is a lightweight component that includes text input and a calendar pop-up to allow users to easily select start and end date values. It can be customized to match app requirements with features like range restrictions, formats, data range selection, grouping the start and end values together and many more. The Date Range Picker in Angular also allows developers to change the default view property and set it to month, year or multi-year.

Angular Date Range Picker Example

We have created this basic Angular Date Range Picker example to show you the component in action. In this case, you see a calendar pop-up, letting users select start and end date values.

Getting Started with Ignite UI for Angular Date Range Picker

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 IgxDateRangePickerModule in your app.module.ts file.

As IgxDateRangePicker uses the IgxCalendarComponent, it also has a dependency on the BrowserAnimationsModule and optionally the HammerModule for touch interactions, so they need to be added to the AppModule as well:

// app.module.ts

import { IgxDateRangePickerModule } from 'igniteui-angular';
// import { IgxDateRangePickerModule } from '@infragistics/igniteui-angular'; for licensed package

import { HammerModule } from '@angular/platform-browser';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';

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

Alternatively, as of 16.0.0 you can import the IgxDateRangePickerComponent as a standalone dependency, or use the IGX_DATE_RANGE_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_RANGE_PICKER_DIRECTIVES } from 'igniteui-angular';
// import { IGX_DATE_RANGE_PICKER_DIRECTIVES } from '@infragistics/igniteui-angular'; for licensed package

@Component({
    selector: 'app-home',
    template: '<igx-date-range-picker [value]="range"></igx-date-range-picker>',
    styleUrls: ['home.component.scss'],
    standalone: true,
    imports: [BrowserAnimationsModule, HammerModule, IGX_DATE_RANGE_PICKER_DIRECTIVES]
    /* or imports: [BrowserAnimationsModule, HammerModule, IgxDateRangePickerComponent] */
})
export class HomeComponent {}

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

Using the Angular Date Range Picker Component

Display Date Range Picker

To instantiate a date range picker in its default mode, use the following code:

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

public range: DateRange = { start: new Date(2020, 4, 20), end: new Date(2020, 4, 25) };

Note

The Date Range Picker value is of type DateRange, which contains a start and an end date.

To create a two-way data-binding, use ngModel:

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

Projecting components

To enrich the default Date Range Picker UX, the component allows projecting child components - the same as in the IgxInputGroupComponent: igxLabel, igx-hint / igxHint, igx-prefix / igxPrefix, igx-suffix / igxSuffix, excluding IgxInput. More detailed information about this can be found in the Label & Input topic.

In addition, the Ignite UI for Angular Date Range Picker can be configured to project IgxPickerToggleComponent - a component that controls the calendar toggle and can be modified as shown in the Calendar toggle section.

<igx-date-range-picker #dateRangePicker [(ngModel)]="range">
    <label igxLabel>Flight dates</label>
    <igx-hint *ngIf="dateRangePicker.invalid">
        Please choose start and end date!
    </igx-hint>
</igx-date-range-picker>

Display Separate Editable Inputs

The Angular Date Range Picker component also allows configuring two separate inputs for start and end date. This can be achieved by using the IgxDateRangeStartComponent and IgxDateRangeEndComponent as children of the date range picker, as shown in the demo below:

<igx-date-range-picker [(ngModel)]="range">
    <igx-date-range-start>
        <input igxInput igxDateTimeEditor type="text">
    </igx-date-range-start>
    <igx-date-range-end>
        <input igxInput igxDateTimeEditor type="text">
    </igx-date-range-end>
</igx-date-range-picker>

Both the IgxDateRangeStartComponent and IgxDateRangeEndComponent extend the existing IgxInputGroupComponent. For such a configuration to work, defining an IgxInput is required. In addition, all other components and directives available to the IgxInputGroupComponent can also be used.
In order to enable date editing for both inputs, you need to decorate them with igxDateTimeEditor directive.

User Experience

In a default configuration, with a single read-only input, the calendar can be opened by clicking anywhere in the input, including the calendar icon. When there are two separate inputs for start and end date, the calendar can only be opened from the calendar icon, since both inputs are editable by default.

When the calendar is visible, a range can be selected by choosing the start and end dates. Picking a date will set the start and end date, until a second date is chosen. If there is a selected range, clicking any other date from the calendar will start a new range selection.

Start and end date are separated by a hyphen when shown in the component's read-only input. When defining different inputs for start and end, they are separated by the to preposition. The latter can be localized or overwritten via a template. See the Templating example below, for more details.

Examples

Label

To define the label for the date range picker the igxLabel directive should be used as shown in the snippet below:

<igx-date-range-picker [(ngModel)]="range">
    <label igxLabel>Flight dates</label>
</igx-date-range-picker>

Calendar toggle

In the default configuration, with a single read-only input, a default calendar icon is shown as a prefix. The calendar icon 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. To change the default position and show the icon as a suffix, you need to do the following:

<igx-date-range-picker>
    <igx-picker-toggle igxSuffix>
        <igx-icon>calendar_view_day</igx-icon>
    </igx-picker-toggle>
</igx-date-range-picker>

When a Date Range Picker has two separate inputs, for start and end dates, it doesn't expose a calendar icon by default. The IgxPickerToggleComponent should be manually added as a child of the IgxDateRangeStartComponent or IgxDateRangeEndComponent like so:

<igx-date-range-picker>
    <igx-date-range-start>
        ...
        <igx-picker-toggle igxPrefix>
            <igx-icon>calendar_view_day</igx-icon>
        </igx-picker-toggle>
        ...
    </igx-date-range-start>
    <igx-date-range-end>
        ...
    </igx-date-range-end>
</igx-date-range-picker>

Dialog mode

The IgxDateRangePickerComponent component has two modes - dropdown (default) and dialog. To switch to dialog mode, do the following:

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

The range value is set when dates are picked from the calendar. You will notice that in dropdown mode, the Done button is not available.

Custom Action Buttons

The Date Range Picker’s action buttons can be templated using the igxPickerActions directive. A common scenario is allowing the user to select from pre-defined ranges, as in the following demo:

Note

Use the demos for Dialog mode and Display Separate Editable Inputs to try the keyboard combinations defined below.

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

Alt + Down Arrow - Opens the dropdown containing the calendar UI and focuses it
Alt + Up Arrow - Closes the dropdown and focuses the input field (range start input field when two separate inputs are used)
Esc - Closes the dropdown and focuses the input field (range start input field when two separate inputs are used)

Keyboard navigation within the calendar UI of the Date Range Picker is available in all modes and configurations. When the calendar is opened it takes focus and the following keyboard combinations can be used:

Enter selects start and end dates
PageUp, PageDown, Shift + PageUp, Shift + PageDown, Home, End, Tab - navigate the calendar

The calendar keyboard navigation section contains all keyboard combinations that can be used in the calendar.

When two separate inputs are used, keyboard navigation for the igxDateTimeEditor directive is also applicable to the Date Range Picker component:

Ctrl / Cmd + Arrow Left / Right - navigates between date sections. On Ctrl / Cmd + Right it goes to the end of the section. If already there it goes to the end of the next section. It works the same way in the opposite direction.
Arrow Up / Down - increments/decrements date portions.
Ctrl / Cmd + ; - sets the current day and time in the editor.

Formatting

The Date Range Picker Component supports different display and input formats.

The display format of the value can be one of the listed Angular DatePipe formats. This allows it to support predefined format options, such as shortDate and longDate.

The inputFormat property accepts a constructed format string using characters supported by the DatePipe, e.g. MM/dd/yyyy, but doesn't support predefined format options, such as shortDate and longDate. If the inputFormat property is not defined then the Angular locale ID token is used when building it.

<igx-date-range-picker [(ngModel)]="range" required
    inputFormat="dd/MM/yyyy" displayFormat="shortDate">
</igx-date-range-picker>

Note

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

Forms and Validation

The Date Range 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 NgModel and validators can be set on the IgxDateRangePickerComponent or on the individual start and end date inputs.

The following snippets and examples illustrate the use of the required validator in a Template-driven form.

First, we need to set up the model for a single read-only range component, which is done on the component level:

<igx-date-range-picker [(ngModel)]="range" required>
    <label igxLabel>Period</label>
</igx-date-range-picker>

The same configuration can be used when setting two separate inputs. Note that in this case, validation is also applied to both inputs.

<igx-date-range-picker [(ngModel)]="range" required>
    <igx-date-range-start>
        <label igxLabel>Start Date</label>
        <input igxInput igxDateTimeEditor type="text">
        <igx-picker-toggle igxPrefix>
            <igx-icon>calendar_today</igx-icon>
        </igx-picker-toggle>
    </igx-date-range-start>
    <igx-date-range-end>
        <label igxLabel>End Date</label>
        <input igxInput igxDateTimeEditor type="text">
    </igx-date-range-end>
</igx-date-range-picker>

When using two separate inputs, it is possible to set the model and required properties on each input. Note that validation is specific for each individual input.

<igx-date-range-picker>
    <igx-date-range-start>
        <input igxInput igxDateTimeEditor [(ngModel)]="range.start" type="text" required>
    </igx-date-range-start>
    <igx-date-range-end>
        <input igxInput igxDateTimeEditor [(ngModel)]="range.end" type="text" required>
    </igx-date-range-end>
</igx-date-range-picker>

Min and max values

You can specify minValue and maxValue properties to restrict the user input by disabling calendar dates that are outside the range defined by those values.

public minDate = new Date(2020, 1, 15);
public maxDate = new Date(2020, 11, 1);

<igx-date-range-picker [(ngModel)]="range" required
    [minValue]="minDate" [maxValue]="maxDate">
</igx-date-range-picker>

<igx-date-range-picker [minValue]="minDate" [maxValue]="maxDate">
    <igx-date-range-start>
        <input igxInput igxDateTimeEditor [(ngModel)]="range.start" type="text" required>
    </igx-date-range-start>
    <igx-date-range-end>
        <input igxInput igxDateTimeEditor [(ngModel)]="range.end" type="text" required>
    </igx-date-range-end>
</igx-date-range-picker>

The IgxDateRangePickerComponent is also a validator which means it controls its validity internally using minValue and maxValue. You can also access both of them through ngModel:

<igx-date-range-picker #dateRangePicker="ngModel" [(ngModel)]="range" required
    [minValue]="minDate" [maxValue]="maxDate">
    <igx-date-range-start>
        <input igxInput igxDateTimeEditor type="text">
    </igx-date-range-start>
    <igx-date-range-end>
        <input igxInput igxDateTimeEditor type="text">
    </igx-date-range-end>
</igx-date-range-picker>

<!-- minValue & maxValue will be true if the current range does not satisfy them -->
<div *ngIf="dateRangePicker.minValue || dateRangePicker.maxValue">
    <p>Value not in range.</p>
</div>

Templating

When two editors are used, the default separator can be replaced using the igxDateRangeSeparator directive. Here is how to change the date separator to a hyphen -:

<igx-date-range-picker>
    <igx-date-range-start>
        <input igxInput igxDateTimeEditor [(ngModel)]="range.start" type="text" required>
    </igx-date-range-start>
    <ng-template igxDateRangeSeparator>-</ng-template>
    <igx-date-range-end>
        <input igxInput igxDateTimeEditor [(ngModel)]="range.end" type="text" required>
    </igx-date-range-end>
</igx-date-range-picker>

Styling

To get started with styling the igxDateRangePicker, 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 Date Range Picker Component exposes date-range-picker-theme and utilizes several components and directives, including igxInputGroupComponent, igxCalendar and igxOverlay. Any global styling for the aforementioned components and directives will affect the igxDateRangeComponent. As the Date Range Picker Component uses the input group and calendar themes, we have to create new themes that extend the calendar-theme and input-group-theme and use some of their parameters to style the date range picker in conjunction with the date range picker theme. We will use a single custom color palette to define the colors to use across all themes:

// COMMON
$purple: #9E379F;
$blue: #61AEDB;

$custom-palette: palette($primary: $blue, $secondary: $purple);

$today-text: color($custom-palette, "primary", 500);
$text-color: color($custom-palette, "secondary", 200);
$color-focused: color($custom-palette, "secondary", 500);

// DATE-RANGE
$custom-date-range-theme:date-range-picker-theme(
    $label-color: $color-focused
);

// INPUT GROUP
$custom-input-group-theme: input-group-theme(
  $palette: $custom-palette,
  $filled-text-color: $text-color,
  $idle-text-color: $text-color,
  $focused-text-color: $color-focused,
  $hover-bottom-line-color: $color-focused,
  $idle-bottom-line-color: $purple
);

// CALENDAR
$custom-calendar-theme: calendar-theme(
    $palette: $custom-palette,
    $date-current-text-color: $today-text,
    $border-radius: 0.5,
    $date-border-radius: 0.5
);

Using CSS variables

The last step is to pass the custom themes:

@include css-vars($custom-date-range-theme);
@include css-vars($custom-input-group-theme);
@include css-vars($custom-calendar-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 it using ::ng-deep. To prevent the custom theme from leaking into other components, be sure to include the :host selector before ::ng-deep:

:host {
   ::ng-deep {
       @include date-range-picker($custom-date-range-theme);
       @include input-group($custom-input-group-theme);
       @include calendar($custom-calendar-theme);
   }
}

Scoping Styles

Regarding style scoping, you should refer to both styling sections [Overlay Scoped Component Styles](overlay-styling.md#Scoped Overlay Styles) and Input Group Scoping Styles as they provide more information.

Application Demo

The demo below defines a form for flight tickets that uses the IgxDateRangePickerComponent. If no dates are selected, an IgxHint is used to display a validation error. The selection of the dates is restricted by the minValue and maxValue properties of the IgxDateRangePickerComponent

Angular Date Range Picker Component Overview

Angular Date Range Picker Example

Getting Started with Ignite UI for Angular Date Range Picker

Using the Angular Date Range Picker Component

Display Date Range Picker

Note

Projecting components

Display Separate Editable Inputs

User Experience

Examples

Label

Calendar toggle

Dialog mode

Custom Action Buttons

Keyboard Navigation

Note

Formatting

Note

Forms and Validation

Min and max values

Templating

Styling

Using CSS variables

Using Theme Overrides

Scoping Styles

Application Demo

API References

Theming Dependencies

Additional Resources

Theming