Below is a sample demonstrating theIgxDateRangePickerComponent 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 AngularIgxDateRangePickerComponent 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 thegetting started topic.

The next step is to import theIgxDateRangePickerModule in yourapp.module.ts file.

As theIgxDateRangePickerComponent uses theIgxCalendarComponent, it also has a dependency on theBrowserAnimationsModule andoptionally theHammerModule for touch interactions, so they need to be added to theAppModule as well:

// app.module.tsimport { IgxDateRangePickerModule } from 'igniteui-angular';// import { IgxDateRangePickerModule } from '@infragistics/igniteui-angular'; for licensed packageimport { HammerModule } from '@angular/platform-browser';import { BrowserAnimationsModule } from '@angular/platform-browser/animations';@NgModule({    ...    imports: [..., IgxDateRangePickerModule, BrowserAnimationsModule, HammerModule],    ...})export class AppModule {}

Alternatively, as of16.0.0 you can import theIgxDateRangePickerComponent as a standalone dependency, or use theIGX_DATE_RANGE_PICKER_DIRECTIVES token to import the component and all of its supporting components and directives.

// home.component.tsimport { 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 theigx-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) };

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, usengModel:

<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 theIgxDateRangeStartComponent andIgxDateRangeEndComponent 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 theIgxDateRangeStartComponent andIgxDateRangeEndComponent extend the existingIgxInputGroupComponent. For such a configuration to work, defining anIgxInput is required. In addition, all other components and directives available to theIgxInputGroupComponent can also be used.
• In order to enable date editing for both inputs, you need to decorate them withigxDateTimeEditor directive.

Popup modes

By default, when clicked, theIgxDateRangePickerComponent opens its calendar pop-up indropdown mode. Alternatively, the calendar can be opened indialog mode by setting theMode property todialog.

<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 indialog 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, theDone button is not available. In dialog mode, aCancel button allows to revert the selection on close.

Keyboard Navigation

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

Both Single and Two Inputs Modes:

Thecalendar 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 theIgxInputGroupComponent:igxLabel,igx-hint / igxHint,igx-prefix / igxPrefix,igx-suffix / igxSuffix, excludingIgxInput. More detailed information about this can be found in theLabel & 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 theIgxPickerToggleComponent andIgxPickerClearComponent. They can be decorated with eitherigxPrefix origxSuffix, 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. TheIgxPickerToggleComponent andIgxPickerClearComponent should be manually added as children of theIgxDateRangeStartComponent orIgxDateRangeEndComponent 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 thecustomRanges 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 theusePredefinedRanges 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 theigxPickerActions 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 AngularDatePipe formats. This allows it to support predefined format options, such asshortDate andlongDate.

TheinputFormat 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 asshortDate andlongDate. If theinputFormat property is not defined then theAngular 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 theinputFormat property is not set, the input format will be inferred from thedisplayFormat in case it can be parsed as containing numeric date-time parts only.

Forms and Validation

The Date Range Picker Component supports all directives from the coreFormsModule,NgModel andReactiveFormsModule (FormControl,FormGroup, etc.). This also includes theForms Validators functions. In addition, the component'smin and max values anddisabledDates also act as form validators.

TheNgModel and validators can be set on theIgxDateRangePickerComponent or on the individual start and end date inputs.

The following snippets and examples illustrate the use of therequired 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 specifyminValue andmaxValue 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>

TheIgxDateRangePickerComponent is also a validator which means it controls its validity internally usingminValue andmaxValue. You can also access both of them throughngModel:

<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 thedisabledDates 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 theDisabledDates 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 theSpecialDates property instead.Special dates

Templating

When two editors are used, the default separator can be replaced using theigxDateRangeSeparator 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 theIgxCalendarComponent topic.

 <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 theigxCalendarHeader,igxCalendarSubheader and theigxCalendarHeaderTitle 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 theigxDateRangePicker, we need to import theindex 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 exposesdate-range-picker-theme and utilizes several components and directives, includingigxInputGroupComponent,igxCalendar andigxOverlay. Any global styling for the aforementioned components and directives will affect theigxDateRangeComponent. As the Date Range Picker Component uses the input group and calendar themes, we have to create new themes that extend thecalendar-theme andinput-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);

: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) andInput Group Scoping Styles as they provide more information.

Application Demo

The demo below defines a form for flight tickets that uses theIgxDateRangePickerComponent. If no dates are selected, anIgxHint is used to display a validation error. The selection of the dates is restricted by theminValue andmaxValue properties of theIgxDateRangePickerComponent

API References

• IgxDateRangePickerComponent
• IgxCalendarComponent
• IgxCalendarComponent Styles
• IgxOverlay Styles
• IgxInputGroupComponent

Theming Dependencies

• IgxCalendar Theme
• IgxOverlay Theme
• IgxIcon Theme
• IgxButton Theme
• IgxInputGroup Theme
• IgxDropDown Theme

Additional Resources

Related topics:

• Date Time Editor
• Label & Input
• Reactive Forms Integration
• Date Picker

Our community is active and always welcoming to new ideas.

• Ignite UI for AngularForums
• Ignite UI for AngularGitHub