Web Components Date Range Picker Overview

The Ignite UI for Web Components 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.

Date Range Picker Example

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

Getting Started

To start using the DateRangePicker, you first need to install the Ignite UI for Web Components by running the following command:

npm install igniteui-webcomponents

After that, you need to import the DateRangePicker, its necessary CSS, and register its module, as follows:

import { defineComponents, IgcDateRangePickerComponent } from 'igniteui-webcomponents';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

defineComponents(IgcDateRangePickerComponent);

Now you can start with a basic configuration of the Web Components DateRangePicker.

For a complete introduction to the Ignite UI for Web Components, read the Getting Started topic.

Usage

The DateRangePicker allows users to select a start and end date either by choosing a date range from a dropdown/calendar pop-up or by typing directly into the input fields - one for the start date and one for the end date. The picker offers two modes for displaying date values: single input and two inputs. Both provide editing and masking capabilities.

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.

Display Date Range Picker

To instantiate a DateRangePicker in its default single input mode, use the following code:

<igc-date-range-picker>
</igc-date-range-picker>

To switch the DateRangePicker to use two inputs, set the DateRangePicker.useTwoInputs property to true.

<igc-date-range-picker use-two-inputs="true">
</igc-date-range-picker>

Value

In addition to being selected or typed by the user, the range value of the DateRangePicker can also be set using the DateRangePicker.value property. It’s important to note that the value must follow the format: { start: startDate, end: endDate }, where startDate and endDate are Date objects representing the selected range.

let dateRange = document.querySelector('igc-date-range-picker') as IgcDateRangePickerComponent;
let startDate = new Date(2025, 4, 6);
let endDate = new Date(2025, 4, 8);
dateRange.value = { start: startDate, end: endDate }

In addition, the value can be set as attribute. In this case it should represent an object that can be parsed correctly as JSON, where the start and end fields should have date values in the ISO 8601 format:

<igc-date-range-picker value='{"start":"2025-01-01","end":"2025-01-02"}'>
<igc-date-range-picker/>

Read-only & Non-editable

You can also make the DateRangePicker read-only, which disables changing the range value through both typing and calendar selection, disables keyboard navigation, and makes the calendar and clear icons appear visually disabled. This is useful when the range is assigned via the value attribute and is intended to be display-only. To enable this behavior, simply set the DateRangePicker.readOnly property.

<igc-date-range-picker use-two-inputs="true" readonly>
</igc-date-range-picker>

Alternatively, you can use the DateRangePicker.nonEditable property, which, unlike DateRangePicker.readOnly, only prevents editing the input(s) via typing, while still allowing selection through the calendar and clearing via the clear icon.

<igc-date-range-picker use-two-inputs="true" non-editable="true">
</igc-date-range-picker>

Popup modes

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

<igc-date-range-picker mode="dialog">
</igc-date-range-picker>

Keyboard Navigation

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

You can also navigate within the calendar pop-up using the keyboard. The navigation is the same as in the Calendar component.

Layout

Label

You can define a label for the DateRangePicker component using the DateRangePicker.label property when it is in single input mode. In two inputs mode, you can use the DateRangePicker.labelStart and DateRangePicker.labelEnd properties to define labels for the start and end date input fields, respectively.

<igc-date-range-picker label="Date Range">
</igc-date-range-picker>

<igc-date-range-picker use-two-inputs="true" label-start="Start Date" label-end="End Date">
</igc-date-range-picker>

Format

You also have the option to customize the date format displayed in the input fields. There are three properties available for this purpose: DateRangePicker.locale, DateRangePicker.inputFormat, and DateRangePicker.displayFormat.

The DateRangePicker.locale property allows you to set the desired locale identifier, which determines how the date is formatted based on regional conventions. For example, to display the date in a Japanese format, you can set the locale property like this:

<igc-date-range-picker locale="ja-JP">
</igc-date-range-picker>

If you want to manually define the date format, you can use the DateRangePicker.inputFormat property by passing a custom format string:

<igc-date-range-picker input-format="dd/MM/yy">
</igc-date-range-picker>

The DateRangePicker.displayFormat property also accepts a custom format string, but it only applies when the input field is idle (i.e., not focused). When the field is focused, the format reverts to the default or to the one defined by DateRangePicker.inputFormat, if both properties are used together:

<igc-date-range-picker input-format="dd/MM/yy" display-format="yy/MM/dd">
</igc-date-range-picker>

Calendar Layout and Formatting

You can further customize the pop-up calendar using various properties:

<igc-date-range-picker orientation="vertical" visible-months="1" show-week-numbers="true">
</igc-date-range-picker>

Min & Max

You can also set the DateRangePicker.min and DateRangePicker.max properties to restrict user input by disabling calendar dates outside the defined range. These properties act as validators, so even if the user manually types a date outside the range, the DateRangePicker will become invalid.

<igc-date-range-picker min="2025-05-06" max="2025-05-10">
</igc-date-range-picker>

Custom & Predefined Date Ranges

You can also add custom date range chips to the calendar pop-up for faster range selection using the DateRangePicker.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 DateRangePicker.usePredefinedRanges property, a set of predefined ranges chips will be displayed along with the custom ones.

const today = new Date();

const nextSeven = new Date(
  today.getFullYear(),
  today.getMonth(),
  today.getDate() + 7
);
const nextWeek: CustomDateRange[] = [
  {
    label: 'Next 7 days',
    dateRange: {
      start: today,
      end: nextSeven
    }
  }
]

const dateRange = document.querySelector('igc-date-range-picker') as IgcDateRangePickerComponent;
dateRange.customRanges = nextWeek;
dateRange.usePredefinedRanges = true;

Now, when you click the newly created “Next 7 days” chip in the calendar pop-up, the range will automatically be selected, from today through the next 7 days.

Disabled & 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 DateRangePicker.disabledDates property.

let dateRange = document.querySelector('igc-date-range-picker') as IgcDateRangePickerComponent;

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

dateRange.disabledDates = [
  {
    type: DateRangeType.Between,
    dateRange: [minDate, maxDate]
  }
] as DateRangeDescriptor[];

You can see more information about all the possibilities that the DateRangePicker.disabledDates property offers here: 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 DateRangePicker.specialDates property instead. Special dates

Forms

The DateRangePicker component can also be used seamlessly with the HTML form element. The DateRangePicker.min, DateRangePicker.max, and DateRangePicker.required properties act as form validators.

Additional configuration

Properties

In addition to the properties we’ve already covered, the DateRangePicker component offers a variety of additional properties that allow you to further configure its behavior.

Slots

You also have the ability to add custom content and modify the appearance of the DateRangePicker component using the available slots.

The prefix and suffix slots allow you to insert custom content before or after the input field (only available in single input mode):

<igc-date-range-picker>
  <igc-icon slot="prefix" name="down_arrow_icon"></igc-icon>
  <igc-icon slot="suffix" name="upload_icon"></igc-icon>
</igc-date-range-picker>

In two inputs mode, you can use the prefix-start, prefix-end, suffix-start, and suffix-end slots instead to target the individual inputs.

Another set of useful slots are clear-icon and calendar-icon, which allow you to customize the icons for the clear and calendar buttons in the input fields:

<igc-date-range-picker>
  <igc-icon slot="clear-icon" name="apps_icon"></igc-icon>
  <igc-icon slot="calendar-icon" name="bin_icon"></igc-icon>
</igc-date-range-picker>

In two inputs mode, you can also customize the default “to” text between the fields by using the separator slot:

<igc-date-range-picker use-two-inputs="true">
  <span slot="separator">till</span>
</igc-date-range-picker>

The actions slot allows you to insert a custom action button with your own logic. For example, the button below toggles week numbers column in the calendar:

<igc-date-range-picker id="DateRange">
  <igc-button slot="actions" onclick="DateRange.showWeekNumbers = true">Toggle Week Numbers</igc-button>
</igc-date-range-picker>

In addition to the slots we’ve already covered, the following slots are also available in the DateRangePicker component:

Methods

In addition to the properties and slots, the DateRangePicker also exposes few methods that you can use:

Styling

Since the DateRangePicker component uses the Calendar component, it also inherits the Calendar’s CSS parts, allowing you to style both components seamlessly. You can find the full list of exposed Calendar CSS parts here: Calendar Styling. In addition to the Calendar’s CSS parts, the DateRangePicker also exposes some unique CSS parts that you can use to customize its appearance:

igc-date-range-picker::part(label) {
  color: var(--ig-gray-600);
}

igc-date-range-picker::part(calendar-icon-start),
igc-date-range-picker::part(calendar-icon-end) {
  background-color: var(--ig-primary-500);
  color: var(--ig-primary-500-contrast);
}

igc-date-range-picker::part(calendar-icon-open-start),
igc-date-range-picker::part(calendar-icon-open-end) {
  background-color: var(--ig-primary-700);
  color: var(--ig-primary-700-contrast);
}

igc-date-range-picker::part(clear-icon-start),
igc-date-range-picker::part(clear-icon-end) {
  background-color: var(--ig-error-500);
  color: var(--ig-error-500-contrast);
}

API References

Additional Resources

• Ignite UI for Web Components Forums
• Ignite UI for Web Components GitHub