Date Range Picker Component

The Ignite UI for Angular Date Range Picker Component displays a month-view calendar that lets the end-user select a date range by defining its start and end date. The calendar's UI is shown either in a dialog (default) or as a dropdown upon user interaction with the calendar icon that is part of the input field. In addition, the component provides an advanced setup option, exposing two separate editable input fields. The component supports locales and custom date formatting.

Usage

First Steps

To get started with the Ignite UI for Angular Date Range Picker Component, let's first import the IgxDateRangePickerModule in the app.module.ts file.

As IgxDateRangePicker uses the IgxCalendarComponent, it also has a dependency on the BrowserAnimationsModule and 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 { HammerModule } from "@angular/platform-browser";
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';

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

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, IgxHint, igxPrefix, igxSuffix, excluding IgxInput. More detailed information about this can be found in the Label & Input topic.

In addition, the 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 [(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 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>

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>

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

<igx-date-range-picker [mode]="'dropdown'"></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.

Keyboard Navigation

Note: Use the demos for Dropdown 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>

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-start>
        <input igxInput igxDateTimeEditor [(ngModel)]="range.start" type="text" required>
    </igx-date-start>
    <igx-date-end>
        <input igxInput igxDateTimeEditor [(ngModel)]="range.end" type="text" required>
    </igx-date-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-start>
        <input igxInput igxDateTimeEditor [(ngModel)]="range.start" type="text" required>
    </igx-date-start>
    <igx-date-end>
        <input igxInput igxDateTimeEditor [(ngModel)]="range.end" type="text" required>
    </igx-date-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-start>
        <input igxInput igxDateTimeEditor type="text">
    </igx-date-start>
    <igx-date-end>
        <input igxInput igxDateTimeEditor type="text">
    </igx-date-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-start>
        <input igxInput igxDateTimeEditor [(ngModel)]="range.start" type="text" required>
    </igx-date-start>
    <ng-template igxDateRangeSeparator>-</ng-template>
    <igx-date-end>
        <input igxInput igxDateTimeEditor [(ngModel)]="range.end" type="text" required>
    </igx-date-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:

@import '~igniteui-angular/lib/core/styles/themes/index';

The Date Range Picker Component exposes igx-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 igx-calendar-theme and igx-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: igx-palette($primary: $blue, $secondary: $purple);

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

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

// INPUT GROUP
$custom-input-group-theme: igx-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: igx-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 igx-css-vars($custom-date-range-theme);
@include igx-css-vars($custom-input-group-theme);
@include igx-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 igx-date-range-picker($custom-date-range-theme);
       @include igx-input-group($custom-input-group-theme);
       @include igx-calendar($custom-calendar-theme);
   }
}

Scoping Styles

Regarding style scoping, you should refer to both styling sections Overlay Scoped Component 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

API References

Additional Resources

Related topics:

Our community is active and always welcoming to new ideas.