Date Range Picker

The Date Range Picker allows users to select a custom date range in the calendar. They can also navigate from one month to another. Date range pickers are especially helpful when a user needs to understand a date range in the context of other possible dates. For example, when there are limitations on the earliest possible start date (selections beyond that date would not be possible and dates would be faded out), or if only selections in the past can be made.

Unless used as the inline variant, the date range picker consists of two components: the trigger and the date range picker itself. Valid trigger components would be a Button or an Input. The trigger component should always reflect the currently selected date range, or a placeholder text (date format in case of an input, call to action label in case of button) if no selection has been made yet.

note

For a single date selection refer to the SingleDatePicker

Usage Rules

Do

• Use if the user wants to enter a date range

Don't

• Use if the user wants to enter a specific date. In this case, use the SingleDatePicker instead.

Example

Live Editor

function DateRangeInput() { const [dateRange, setDateRange] = useState({ startDate: null, endDate: null }); const { startDate, endDate } = dateRange; // Get the current date at midnight const today = new Date(); const formattedDateRange = `${ startDate ? startDate.toLocaleDateString() : '' } – ${endDate ? endDate.toLocaleDateString() : ''}`; return ( <> <p style={{ marginBottom: Spacing15 }}> Selected date range: {formattedDateRange} </p> <DateRangePicker startDate={dateRange.startDate} endDate={dateRange.endDate} onChange={(startDate, endDate) => { setDateRange({ startDate, endDate }); }} minDate={today} css={{ marginTop: Spacing15 }} dataTestIdNextSelection="custom-datatestid-next" dataTestIdPrevSelection="custom-datatestid-prev" /> </> ); }

function DateRangeInput() {
  const [dateRange, setDateRange] = useState({
    startDate: null,
    endDate: null
  });

  const { startDate, endDate } = dateRange;

  // Get the current date at midnight
  const today = new Date();

  const formattedDateRange = `${
    startDate ? startDate.toLocaleDateString() : ''
  } –  ${endDate ? endDate.toLocaleDateString() : ''}`;

  return (
    <>
      <p style={{ marginBottom: Spacing15 }}>
        Selected date range: {formattedDateRange}
      </p>
      <DateRangePicker
        startDate={dateRange.startDate}
        endDate={dateRange.endDate}
        onChange={(startDate, endDate) => {
          setDateRange({ startDate, endDate });
        }}
        minDate={today}
        css={{ marginTop: Spacing15 }}
        dataTestIdNextSelection="custom-datatestid-next"
        dataTestIdPrevSelection="custom-datatestid-prev"
      />
    </>
  );
}

Result

Loading...

Variants

Position of the current month

By default, the current month is displayed on the left side but you can change this behavior by providing currentMonthPosition prop.

Live Editor

function CurrentMonthPosition() { const [dateRange, setDateRange] = useState({ startDate: null, endDate: null }); return ( <DateRangePicker startDate={dateRange.startDate} endDate={dateRange.endDate} onChange={(startDate, endDate) => { setDateRange({ startDate, endDate }); }} currentMonthPosition="right" /> ); }

function CurrentMonthPosition() {
  const [dateRange, setDateRange] = useState({
    startDate: null,
    endDate: null
  });

  return (
    <DateRangePicker
      startDate={dateRange.startDate}
      endDate={dateRange.endDate}
      onChange={(startDate, endDate) => {
        setDateRange({ startDate, endDate });
      }}
      currentMonthPosition="right"
    />
  );
}

Result

Loading...

Localization

The Date Range Picker has localization support. To make localization active, you can use the locale prop.

info

Supported languages:

English (Default), Chinese, French, German, Japanese, Korean, Portuguese, Russian, Spanish, Turkish, Vietnamese

Live Editor

function CurrentMonthPosition() { const [dateRange, setDateRange] = useState({ startDate: null, endDate: null }); return ( <DateRangePicker startDate={dateRange.startDate} endDate={dateRange.endDate} onChange={(startDate, endDate) => { setDateRange({ startDate, endDate }); }} currentMonthPosition="right" locale="tr" /> ); }

function CurrentMonthPosition() {
  const [dateRange, setDateRange] = useState({
    startDate: null,
    endDate: null
  });

  return (
    <DateRangePicker
      startDate={dateRange.startDate}
      endDate={dateRange.endDate}
      onChange={(startDate, endDate) => {
        setDateRange({ startDate, endDate });
      }}
      currentMonthPosition="right"
      locale="tr"
    />
  );
}

Result

Loading...

Highlighting a reference period

Highlight a reference period. Reference period date numbers will have a distinctive color. Note: This period won't be used in user's selection.

Live Editor

function HighlightingReferencePeriod() { return ( <DateRangePicker referenceStartDate={new Date('2022-08-08')} referenceEndDate={new Date('2022-08-20')} /> ); }

function HighlightingReferencePeriod() {
  return (
    <DateRangePicker
      referenceStartDate={new Date('2022-08-08')}
      referenceEndDate={new Date('2022-08-20')}
    />
  );
}

Result

Loading...

If set programmatically (by props), selected period and reference period can be outside of the maxDate specified.

Live Editor

function ReferenceAndSelectedPeriodOutsideOfMaxDate() { return ( <DateRangePicker maxDate={new Date('2022-08-06')} referenceStartDate={new Date('2022-08-08')} referenceEndDate={new Date('2022-08-12')} startDate={new Date('2022-08-14')} endDate={new Date('2022-08-18')} /> ); }

function ReferenceAndSelectedPeriodOutsideOfMaxDate() {
  return (
    <DateRangePicker
      maxDate={new Date('2022-08-06')}
      referenceStartDate={new Date('2022-08-08')}
      referenceEndDate={new Date('2022-08-12')}
      startDate={new Date('2022-08-14')}
      endDate={new Date('2022-08-18')}
    />
  );
}

Result

Loading...

Custom Current Date

You can pass currentDate. Its value will be assigned to "today".

Live Editor

function CurrentMonthPosition() { const [dateRange, setDateRange] = useState({ startDate: null, endDate: null }); return ( <DateRangePicker startDate={dateRange.startDate} endDate={dateRange.endDate} onChange={(startDate, endDate) => { setDateRange({ startDate, endDate }); }} currentDate="Jan 28 2023" /> ); }

function CurrentMonthPosition() {
  const [dateRange, setDateRange] = useState({
    startDate: null,
    endDate: null
  });

  return (
    <DateRangePicker
      startDate={dateRange.startDate}
      endDate={dateRange.endDate}
      onChange={(startDate, endDate) => {
        setDateRange({ startDate, endDate });
      }}
      currentDate="Jan 28 2023"
    />
  );
}

Result

Loading...

Props

Name	Type	Default
onChange The handler will be called when both values of the date range are selected and there is no onStateChange handler provided	((startDate: Date, endDate: Date) => void)	—
onStateChange The handler will be called if at least one date or focused input has been changed. If provided onChange handler won't be called.	((state: OnDatesChangeProps) => void)	—
startDate The beginning date of the selected date range.	Date | null	null
endDate The end date of the selected date range.	Date | null	null
referenceStartDate The beginning date of the reference date range to highlight.	Date | null	null
referenceEndDate The end date of the reference date range to highlight.	Date | null	null
minDate The earliest date the user can select	Date	—
maxDate The latest date the user can select	Date	—
currentDate The custom date to be used as the current date. If undefined, the machine current date is used.	string | number | Date	—
currentMonthPosition Use this prop to set the position of the current month	"left" | "right"	"left"
isPeriodClicked Boolean prop for Period clicked on the DatepickerButton component	boolean	—
handlePeriodClicked State handler to set PeriodClicked prop	((state: boolean) => void)	—
locale Use this prop to set localization for the date values	"tr" | "en" | "de" | "es" | "fr" | "ja" | "ko" | "pt" | "ru" | "vi" | "zh"	—
dataTestIdNextSelection Next slection data-testid	string	—
dataTestIdPrevSelection Previous slection data-testid	string	—
css Add custom styles to this component. Use with caution. Learn more here: Link	SupportedStyleAttributes	—
inputFieldCss	SupportedStyleAttributes	—
data-{foo} Data attributes can be used by testing libraries to retrieve components or assert their existence	string	—
* - the prop is required.

Related Components

• SingleDatePicker