React Date Range Picker Overview

    The Ignite UI for React 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 IgrDateRangePicker component in action, where a calendar pop-up allows users to select start and end dates.

    Getting Started

    To start using the IgrDateRangePicker, you first need to install the Ignite UI for React by running the following command:

    npm install igniteui-react

    After that, you need to import the IgrDateRangePicker and its necessary CSS, as follows:

    import { IgrDateRangePicker } from 'igniteui-react';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

    Now you can start with a basic configuration of the React IgrDateRangePicker.

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

    Usage

    The IgrDateRangePicker 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. 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.

    Display Date Range Picker

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

    <IgrDateRangePicker/>

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

    <IgrDateRangePicker useTwoInputs/>

    Value

    In addition to being selected or typed by the user, the range value of the IgrDateRangePicker can also be set using the 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.

    const dateRangeRef = useRef<IgrDateRangePicker>();
let startDate = new Date(2025, 4, 6);
let endDate = new Date(2025, 4, 8);
useEffect (() => {
  dateRangeRef.current.value = { start: startDate, end: endDate }
}, [])

return (
  <IgrDateRangePicker ref={dateRangeRef} />
);

    <IgrDateRangePicker value={{start: new Date('2025-01-01'), end: new Date('2025-01-02')}}/>

    Read-only & Non-editable

    You can also make the IgrDateRangePicker 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 readOnly property.

    <IgrDateRangePicker useTwoInputs readOnly/>

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

    <IgrDateRangePicker useTwoInputs nonEditable/>

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

    <IgrDateRangePicker mode='dialog'/>

    Keyboard Navigation

    The IgrDateRangePicker 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 + ↓ Opens the calendar dropdown
    ALT + ↑ Closes the calendar dropdown

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

    Keys Description
    ↑ / ↓ / ← / → Navigates through the days in the month
    ENTER Selects the currently focused day
    PAGE UP Moves to the previous month's view
    PAGE DOWN Moves to the next month's view
    SHIFT + PAGE UP Moves to the previous year
    SHIFT + PAGE DOWN Moves to the next year
    HOME Focuses the first day of the current month that is in view (or earliest month when more than one month view is displayed)
    END Focuses the last day of the current month that is in view. (or latest month when more than one month view is displayed)
    Escape Closes the calender pop-up

    Layout

    Label

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

    <IgrDateRangePicker label='Date Range'/>

    <IgrDateRangePicker useTwoInputs labelStart='Start Date' labelEnd='End Date'/>

    Format

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

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

    <IgrDateRangePicker locale='ja-JP'/>

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

    <IgrDateRangePicker inputFormat='dd/MM/yy'/>

    The 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 inputFormat, if both properties are used together:

    <IgrDateRangePicker inputFormat='dd/MM/yy' displayFormat='yy/MM/dd'/>

    Calendar Layout and Formatting

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

    Name Type Description
    orientation 'vertical' or 'horizontal' Allows you to set whether the calendar should be displayed vertically or horizontally.
    visibleMonths 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.
    open boolean Determines whether the calendar picker is open.
    keepOpenOnSelect boolean Keeps the calendar picker open after a date selection.
    keepOpenOnOutsideClick boolean Keeps the calendar picker open when clicking outside of it.
    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. 
    <IgrDateRangePicker orientation='vertical' visibleMonths={1} showWeekNumbers/>

    Min & Max

    You can also set the min and 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 IgrDateRangePicker will become invalid.

    <IgrDateRangePicker min={new Date('2025-05-06')} max={new Date('2025-05-10')}/>

    Custom & 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.

    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
    }
  }
];

return (
  <IgrDateRangePicker usePredefinedRanges customRanges={nextWeek} />
);

    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 disabledDates property.

    const dateRangeRef = useRef<IgrDateRangePicker>();
const minDate = new Date(2025, 4, 5);
const maxDate = new Date(2025, 4, 15);
useEffect (() => {
  dateRangeRef.current.disabledDates = [
    {
      type: DateRangeType.Between,
      dateRange: [minDate, maxDate]
    }
  ] as DateRangeDescriptor[];
}, [])

return (
  <IgrDateRangePicker ref={dateRangeRef} />
);

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

    Forms

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

    Additional configuration

    Properties

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

    Name Type Description
    disabled boolean Disables the component.
    nonEditable boolean Disables typing in the input field(s).
    placeholder string Placeholder text for the single input mode.
    placeholderStart string Placeholder text for the start date input (two inputs mode).
    placeholderEnd string Placeholder text for the end date input (two inputs mode).
    outlined boolean Determines whether the input part will have outline appearance in the Material theme.
    prompt string The prompt character used for unfilled parts of the input(s) mask.
    resourceStrings IgcDateRangePickerResourceStrings Resource strings for localization of the date-range picker and the calendar.

    Slots

    You also have the ability to add custom content and modify the appearance of the IgrDateRangePicker 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):

    <IgrDateRangePicker>
  <IgrIcon slot='prefix' name='down_arrow_icon'></IgrIcon>
  <IgrIcon slot='suffix' name='upload_icon'></IgrIcon>
</IgrDateRangePicker>

    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:

    <IgrDateRangePicker>
  <IgrIcon slot="clear-icon" name="apps_icon"></IgrIcon>
  <IgrIcon slot="calendar-icon" name="bin_icon"></IgrIcon>
</IgrDateRangePicker>

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

    <IgrDateRangePicker useTwoInputs>
  <span slot='separator'>till</span>
</IgrDateRangePicker>

    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:

    const dateRangeRef = useRef<IgrDateRangePicker>();
const toggleWeekNumbers = () => {
  dateRangeRef.current.showWeekNumbers = !dateRangeRef.current.showWeekNumbers;
};

return (
  <IgrDateRangePicker ref={dateRangeRef}>
    <IgrButton slot="actions" onClick={toggleWeekNumbers}>Toggle Week Numbers</IgrButton>
  </IgrDateRangePicker>
);

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

    Name Description
    title Renders content for the calendar title. Applicable only in dialog mode.
    helper-text Renders content below the input field(s).
    header-date Replaces the default current date/range text in the calendar header. Applicable only in dialog mode.
    clear-icon-start Custom clear icon for the start input (two inputs mode).
    clear-icon-end Custom clear icon for the end input (two inputs mode).
    calendar-icon-start Custom calendar icon for the start input (two inputs mode).
    calendar-icon-end Custom calendar icon for the end input (two inputs mode).
    calendar-icon-open Icon or content shown when the picker is open (applies to both inputs in two inputs mode).
    calendar-icon-open-start Icon or content for the open state of the start input (two inputs mode).
    calendar-icon-open-end Icon or content for the open state of the end input (two inputs mode).

    Methods

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

    Name Description
    show Displays the calendar picker component.
    hide Hides the calendar picker component.
    toggle Toggles the calendar picker between the shown and hidden states.
    clear Clears the input fields, removing any user input.
    select Selects a date range value in the picker.
    setCustomValidity Sets a custom validation message. If the provided message is not empty, the input will be marked as invalid.

    Styling

    Since the IgrDateRangePicker component uses the IgrCalendar 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 IgrDateRangePicker also exposes some unique CSS parts that you can use to customize its appearance:

    Name Description
    separator The separator element between the two inputs.
    ranges The wrapper that renders the custom and predefined ranges.
    label The label wrapper that renders content above the target input.
    container The main wrapper that holds all main input elements.
    input The native input element.
    prefix The prefix wrapper.
    suffix The suffix wrapper.
    calendar-icon The calendar icon wrapper for the closed state.
    calendar-icon-start The calendar icon wrapper for the closed state of the start input (two inputs).
    calendar-icon-end The calendar icon wrapper for the closed state of the end input (two inputs).
    calendar-icon-open The calendar icon wrapper for the open state.
    calendar-icon-open-start The calendar icon wrapper for the open state of the start input (two inputs).
    calendar-icon-open-end The calendar icon wrapper for the open state of the end input (two inputs).
    clear-icon The clear icon wrapper (single input).
    clear-icon-start The clear icon wrapper for the start input (two inputs).
    clear-icon-end The clear icon wrapper for the end input (two inputs).
    actions The actions wrapper.
    helper-text The helper-text wrapper that renders content below the target input. 
    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