Angular Date Range Picker Component Overview

The Angular Date Range Picker is a lightweight component that includes a text input and a calendar pop-up, allowing users to easily select start and end dates. It is highly customizable to fit various application requirements, offering features such as date range restrictions, configurable date formats, and more.

Angular Date Range Picker Example

Below is a sample demonstrating the IgxDateRangePickerComponent component in action, where a calendar pop-up allows users to select start and end dates.

Getting Started with Ignite UI for Angular Date Range Picker

To get started with the Ignite UI for Angular IgxDateRangePickerComponent 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 the IgxDateRangePickerComponent 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 and Value

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.

The picker offers two modes for displaying date values: single input and two inputs. In single input mode, the field is non-editable and the date range cannot be edited by typing. In two inputs mode, however, users can edit the start and end dates by typing in separate input fields.

When the calendar is visible a date range can be selected by choosing both a start and end date. Selecting a date will set both the start and end date and once a second date is chosen, it will set the end date. If a range is already selected, clicking any other date on the calendar will start a new range selection.

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

<igx-date-range-picker [(ngModel)]="range"></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.

By default, when clicked, the IgxDateRangePickerComponent opens its calendar pop-up in dropdown mode. Alternatively, the calendar can be opened in dialog mode by setting the Mode property to dialog.

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

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, and in dropdown mode, the calendar can only be opened from the calendar icon, since both inputs are editable by default. For two inputs in dialog mode, clicking anywhere in the input opens the calendar

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. In dialog mode, a Cancel button allows to revert the selection on close.

The IgxDateRangePickerComponent features intuitive keyboard navigation, allowing users to easily increment, decrement, or jump between different component parts, all without needing to use a mouse.

The available keyboard navigation options vary depending on whether the component is in single input or two inputs mode.

Two Inputs Mode:

Keys	Description
`←`	Moves the caret one character to the left
`→`	Moves the caret one character to the right
`Ctrl + ArrowLeft`	Moves the caret to the beginning of the current input mask section or to the start of the previous one if it's already at the beginning
`Ctrl + ArrowRight`	Moves the caret to the end of the current input mask section or to the end of the next one if it's already at the end
`ArrowUp`	Increments the currently "focused" part of the input mask by one step
`ArrowDown`	Decrements the currently "focused" part of the input mask by one step
`Home`	Moves the caret to the beginning of the input mask
`End`	Moves the caret to the end of the input mask
`Ctrl + ;`	Sets the current date as the value of the component

Both Single and Two Inputs Modes:

Keys	Description
`Alt + ArrowDown`	Opens the calendar dropdown
`Alt + ArrowUp`	Closes the calendar dropdown

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

Layout

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.

<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>

Or for two inputs:

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

Toggle and clear icons

In the default configuration, with a single read-only input, a default calendar icon is shown as a prefix and a clear icon - as a suffix. These icons can be changed or redefined using the IgxPickerToggleComponent and IgxPickerClearComponent. They can be decorated with either igxPrefix or igxSuffix, which will define their position - at the start of the input or at the end respectively:

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

When a Date Range Picker has two separate inputs for start and end dates, it doesn't expose these icons by default. The IgxPickerToggleComponent and IgxPickerClearComponent should be manually added as children 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-picker-clear igxSuffix>
            <igx-icon>clear</igx-icon>
        </igx-picker-clear>
        ...
    </igx-date-range-start>
    <igx-date-range-end>
        ...
    </igx-date-range-end>
</igx-date-range-picker>

Custom And Predefined Date Ranges

You can also add custom date range chips to the calendar pop-up for faster range selection using the customRanges property. For example, you can create a custom date range chip to quickly select the range for the upcoming 7 days, ending with the current date. In addition, by setting the usePredefinedRanges property, a set of predefined ranges chips will be displayed along with the custom ones.

public today = new Date();

public nextSeven = new Date(
    this.today.getFullYear(),
    this.today.getMonth(),
    this.today.getDate() + 7
);

public customRanges: CustomDateRange[] = [
    {
        label: 'Next 7 days',
        dateRange: {
          start: this.today,
          end: this.nextSeven
        }
      }
];

<igx-date-range-picker [usePredefinedRanges]="true" [customRanges]="customRanges"></igx-date-range-picker>

In addition, custom content or actions can be templated using the igxPickerActions directive. The following demo shows the predefined and custom ranges along with the templated actions:

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>

If the inputFormat property is not set, the input format will be inferred from the displayFormat in case it can be parsed as containing numeric date-time parts only.

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 and disabledDates 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>

Disabled And Special dates

You also have the ability to set disabled dates in the calendar to narrow the range of dates the user can choose from. To set the disabled dates, you can use the disabledDates property.

export class DateRangeSampleComponent implements OnInit {
    @ViewChild('dateRange') public dateRange: IgxDateRangePicker;

    public minDate = new Date(2025, 4, 1);
    public maxDate = new Date(2025, 4, 31);

    public ngOnInit() {
        this.dateRange.disabledDates = [
        {
            type: DateRangeType.Between,
            dateRange: [minDate, maxDate]
        }
        ] as DateRangeDescriptor[];
    }
}

You can see more information about all the possibilities that the DisabledDates property offers here: calendar disabled dates.

You can also do the same if you want to set one or more special dates in the calendar; the only difference is that you need to use the SpecialDates property instead. Special dates

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>

Calendar specific settings

You can further customize the pop-up calendar using various properties. More information on how these affect the calendar can be found in the IgxCalendarComponent topic.

Name	Type	Description
`orientation`	'vertical' or 'horizontal'	Allows you to set whether the calendar should be displayed vertically or horizontally.
`displayMonthsCount`	string	Controls how many months are visible at a time, with a value of either 1 or 2.
`showWeekNumbers`	string	Enables or disables the week number column in the calendar.
`weekStart`	string	Sets the start day of the week.
`hideOutsideDays`	boolean	Hides days that fall outside the current month view.
`hideHeader`	boolean	Hides the calendar header (applicable only in dialog mode).
`headerOrientation`	'vertical' or 'horizontal'	Aligns the calendar header vertically or horizontally (dialog mode only).
`activeDate`	Date	Sets the date that is initially highlighted in the calendar. If not set, the current date becomes the active date.

 <igx-date-range-picker [hideHeader]="true"
                        [orientation]="'vertical'"
                        [headerOrientation]="'horizontal'"
                        [displayMonthsCount]="1">
</igx-date-range-picker>

The header, subheader and title parts of the calendar header can be customized by leveraging the igxCalendarHeader, igxCalendarSubheader and the igxCalendarHeaderTitle template directives, for example:

<igx-date-range-picker [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>
    <ng-template igxCalendarHeaderTitle let-format>
    <span>My calendar</span>
  </ng-template>
</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;
$light-gray: #efefef;

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

$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(
  $filled-text-color: $text-color,
  $idle-text-color: $text-color,
  $focused-text-color: $color-focused,
  $idle-bottom-line-color: $purple,
  $hover-bottom-line-color: $color-focused,
  $interim-bottom-line-color: $color-focused
);

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

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);

Warning

If the component is using an Emulated ViewEncapsulation, it is necessary to penetrate this encapsulation using ::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 and Value

Note

Display Separate Editable Inputs

Keyboard Navigation

Layout

Projecting components

Toggle and clear icons

Custom And Predefined Date Ranges

Formatting

Note

Forms and Validation

Min and max values

Disabled And Special dates

Templating

Calendar specific settings

Styling

Warning

Scoping Styles

Application Demo

API References

Theming Dependencies

Additional Resources

Theming

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 and Value

Note

Display Separate Editable Inputs

Popup modes

Keyboard Navigation

Layout

Projecting components

Toggle and clear icons

Custom And Predefined Date Ranges

Formatting

Note

Forms and Validation

Min and max values

Disabled And Special dates

Templating

Calendar specific settings

Styling

Warning

Scoping Styles

Application Demo

API References

Theming Dependencies

Additional Resources

Theming