DateRangePicker

A date range picker combines two DateFields and a RangeCalendar popover to allow users to enter or select a date and time range.

install	`yarn add react-aria-components`
version	3.17.0
usage	`import {DateRangePicker} from 'react-aria-components'`

View repository

GitHub

View package

NPM

Example#

import {Button, CalendarCell, CalendarGrid, DateInput, DateRangePicker, DateSegment, Dialog, Group, Heading, Label, Popover, RangeCalendar} from 'react-aria-components';

<DateRangePicker>
  <Label>Trip dates</Label>
  <Group>
    <DateInput slot="start">
      {(segment) => <DateSegment segment={segment} />}
    </DateInput>
    <span aria-hidden="true">–</span>
    <DateInput slot="end">
      {(segment) => <DateSegment segment={segment} />}
    </DateInput>
    <Button>▼</Button>
  </Group>
  <Popover>
    <Dialog>
      <RangeCalendar>
        <header>
          <Button slot="previous">◀</Button>
          <Heading />
          <Button slot="next">▶</Button>
        </header>
        <CalendarGrid>
          {(date) => <CalendarCell date={date} />}
        </CalendarGrid>
      </RangeCalendar>
    </Dialog>
  </Popover>
</DateRangePicker>

import {
  Button,
  CalendarCell,
  CalendarGrid,
  DateInput,
  DateRangePicker,
  DateSegment,
  Dialog,
  Group,
  Heading,
  Label,
  Popover,
  RangeCalendar
} from 'react-aria-components';

<DateRangePicker>
  <Label>Trip dates</Label>
  <Group>
    <DateInput slot="start">
      {(segment) => <DateSegment segment={segment} />}
    </DateInput>
    <span aria-hidden="true">–</span>
    <DateInput slot="end">
      {(segment) => <DateSegment segment={segment} />}
    </DateInput>
    <Button>▼</Button>
  </Group>
  <Popover>
    <Dialog>
      <RangeCalendar>
        <header>
          <Button slot="previous">◀</Button>
          <Heading />
          <Button slot="next">▶</Button>
        </header>
        <CalendarGrid>
          {(date) => <CalendarCell date={date} />}
        </CalendarGrid>
      </RangeCalendar>
    </Dialog>
  </Popover>
</DateRangePicker>

import {
  Button,
  CalendarCell,
  CalendarGrid,
  DateInput,
  DateRangePicker,
  DateSegment,
  Dialog,
  Group,
  Heading,
  Label,
  Popover,
  RangeCalendar
} from 'react-aria-components';

<DateRangePicker>
  <Label>
    Trip dates
  </Label>
  <Group>
    <DateInput slot="start">
      {(segment) => (
        <DateSegment
          segment={segment}
        />
      )}
    </DateInput>
    <span aria-hidden="true">
      –
    </span>
    <DateInput slot="end">
      {(segment) => (
        <DateSegment
          segment={segment}
        />
      )}
    </DateInput>
    <Button>▼</Button>
  </Group>
  <Popover>
    <Dialog>
      <RangeCalendar>
        <header>
          <Button slot="previous">
            ◀
          </Button>
          <Heading />
          <Button slot="next">
            ▶
          </Button>
        </header>
        <CalendarGrid>
          {(date) => (
            <CalendarCell
              date={date}
            />
          )}
        </CalendarGrid>
      </RangeCalendar>
    </Dialog>
  </Popover>
</DateRangePicker>

Show CSS

.react-aria-DateRangePicker {
  & [role=group] {
    display: flex;
    align-items: center;
    width: fit-content;
    min-width: 220px;
    padding: 2px 2px 2px 8px;
    border: 1px solid var(--spectrum-global-color-gray-400);
    border-radius: 6px;
    background: var(--spectrum-global-color-gray-50);

    &:focus-within {
      border-color: slateblue;
      box-shadow: 0 0 0 1px slateblue;
    }
  }

  & [slot=start] + span {
    padding: 0 4px;
  }

  & [slot=end] {
    margin-right: 2rem;
    flex: 1;
  }

  & button {
    background: slateblue;
    color: white;
    border-radius: 4px;
    border: none;
    appearance: none;
    margin-left: auto;
    width: 1.429rem;
    height: 1.429rem;
    padding: 0;
    vertical-align: middle;
    font-size: 0.857rem;
    outline: none;
    box-sizing: content-box;
    border: 2px solid var(--page-background);

    &[data-focus-visible] {
      box-shadow: 0 0 0 2px slateblue;
    }
  }

  & [slot=description] {
    font-size: 12px;
  }

  & [slot=errorMessage] {
    font-size: 12px;
    color: var(--spectrum-global-color-red-600);
  }
}

.react-aria-DateInput {
  display: flex;
}

.react-aria-DateSegment {
  padding: 0 2px;
  font-variant-numeric: tabular-nums;
  text-align: end;

  &[data-type=literal] {
    padding: 0;
  }

  &[data-placeholder] {
    color: var(--spectrum-global-color-gray-700);
    font-style: italic;
  }

  &:focus {
    color: white;
    background: slateblue;
    outline: none;
    border-radius: 4px;
    caret-color: transparent;
  }

  &[aria-invalid] {
    color: var(--spectrum-global-color-red-600);

    &:focus {
      background: var(--spectrum-global-color-static-red-600);
      color: white;
    }
  }
}

.react-aria-Popover {
  overflow: auto;
  border: 1px solid var(--spectrum-global-color-gray-400);
  box-shadow: 0 8px 20px rgba(0 0 0 / 0.1);
  border-radius: 6px;
  background: var(--page-background);
  padding: 1.25rem;
}

.react-aria-RangeCalendar {
  width: fit-content;

  & header {
    display: flex;
    align-items: center;
    margin-bottom: .5rem;

    & h2 {
      flex: 1;
      margin: 0;
      text-align: center;
      font-size: 1.375rem;
    }

    & button {
      background: var(--spectrum-global-color-gray-50);
      border: 1px solid var(--spectrum-global-color-gray-400);
      box-shadow: 0 1px 2px rgba(0 0 0 / 0.1);
      border-radius: 4px;
      appearance: none;
      vertical-align: middle;
      font-size: 1rem;
      width: 1.75rem;
      height: 1.75rem;
      text-align: center;
      margin: 0;
      outline: none;

      &[data-focus-visible] {
        border-color: slateblue;
        box-shadow: 0 0 0 1px slateblue;
      }

      &[data-pressed] {
        background: var(--spectrum-global-color-gray-100);
      }
    }
  }

  & table {
    margin: 0 -4px;
    border-collapse: collapse;

    & td {
      padding: 2px 0;
    }
  }

  & .react-aria-CalendarCell {
    width: 2.286rem;
    line-height: 2.286rem;
    text-align: center;
    border-radius: 6px;
    cursor: default;
    outline: none;

    &[data-outside-month] {
      display: none;
    }

    &[data-pressed] {
      background: var(--spectrum-global-color-gray-200);
    }

    &[data-focus-visible] {
      box-shadow: inset 0 0 0 2px slateblue;
    }

    &[data-selected] {
      background: slateblue;
      color: white;
      border-radius: 0;

      &[data-focus-visible] {
        box-shadow: inset 0 0 0 1px slateblue, inset 0 0 0 3px white;
      }
    }

    &[data-selection-start] {
      border-start-start-radius: 6px;
      border-end-start-radius: 6px;
    }

    &[data-selection-end] {
      border-start-end-radius: 6px;
      border-end-end-radius: 6px;
    }

    &[data-disabled] {
      color: var(--spectrum-global-color-gray-600); 
    }

    &[data-unavailable] {
      text-decoration: line-through;
      color: var(--spectrum-global-color-red-600);
    }

    &[aria-invalid] {
      background: var(--spectrum-global-color-static-red-600);
      color: white;
    }
  }

  & [slot=errorMessage] {
    font-size: 12px;
    color: var(--spectrum-global-color-red-600);
  }
}

.react-aria-DateRangePicker {
  & [role=group] {
    display: flex;
    align-items: center;
    width: fit-content;
    min-width: 220px;
    padding: 2px 2px 2px 8px;
    border: 1px solid var(--spectrum-global-color-gray-400);
    border-radius: 6px;
    background: var(--spectrum-global-color-gray-50);

    &:focus-within {
      border-color: slateblue;
      box-shadow: 0 0 0 1px slateblue;
    }
  }

  & [slot=start] + span {
    padding: 0 4px;
  }

  & [slot=end] {
    margin-right: 2rem;
    flex: 1;
  }

  & button {
    background: slateblue;
    color: white;
    border-radius: 4px;
    border: none;
    appearance: none;
    margin-left: auto;
    width: 1.429rem;
    height: 1.429rem;
    padding: 0;
    vertical-align: middle;
    font-size: 0.857rem;
    outline: none;
    box-sizing: content-box;
    border: 2px solid var(--page-background);

    &[data-focus-visible] {
      box-shadow: 0 0 0 2px slateblue;
    }
  }

  & [slot=description] {
    font-size: 12px;
  }

  & [slot=errorMessage] {
    font-size: 12px;
    color: var(--spectrum-global-color-red-600);
  }
}

.react-aria-DateInput {
  display: flex;
}

.react-aria-DateSegment {
  padding: 0 2px;
  font-variant-numeric: tabular-nums;
  text-align: end;

  &[data-type=literal] {
    padding: 0;
  }

  &[data-placeholder] {
    color: var(--spectrum-global-color-gray-700);
    font-style: italic;
  }

  &:focus {
    color: white;
    background: slateblue;
    outline: none;
    border-radius: 4px;
    caret-color: transparent;
  }

  &[aria-invalid] {
    color: var(--spectrum-global-color-red-600);

    &:focus {
      background: var(--spectrum-global-color-static-red-600);
      color: white;
    }
  }
}

.react-aria-Popover {
  overflow: auto;
  border: 1px solid var(--spectrum-global-color-gray-400);
  box-shadow: 0 8px 20px rgba(0 0 0 / 0.1);
  border-radius: 6px;
  background: var(--page-background);
  padding: 1.25rem;
}

.react-aria-RangeCalendar {
  width: fit-content;

  & header {
    display: flex;
    align-items: center;
    margin-bottom: .5rem;

    & h2 {
      flex: 1;
      margin: 0;
      text-align: center;
      font-size: 1.375rem;
    }

    & button {
      background: var(--spectrum-global-color-gray-50);
      border: 1px solid var(--spectrum-global-color-gray-400);
      box-shadow: 0 1px 2px rgba(0 0 0 / 0.1);
      border-radius: 4px;
      appearance: none;
      vertical-align: middle;
      font-size: 1rem;
      width: 1.75rem;
      height: 1.75rem;
      text-align: center;
      margin: 0;
      outline: none;

      &[data-focus-visible] {
        border-color: slateblue;
        box-shadow: 0 0 0 1px slateblue;
      }

      &[data-pressed] {
        background: var(--spectrum-global-color-gray-100);
      }
    }
  }

  & table {
    margin: 0 -4px;
    border-collapse: collapse;

    & td {
      padding: 2px 0;
    }
  }

  & .react-aria-CalendarCell {
    width: 2.286rem;
    line-height: 2.286rem;
    text-align: center;
    border-radius: 6px;
    cursor: default;
    outline: none;

    &[data-outside-month] {
      display: none;
    }

    &[data-pressed] {
      background: var(--spectrum-global-color-gray-200);
    }

    &[data-focus-visible] {
      box-shadow: inset 0 0 0 2px slateblue;
    }

    &[data-selected] {
      background: slateblue;
      color: white;
      border-radius: 0;

      &[data-focus-visible] {
        box-shadow: inset 0 0 0 1px slateblue, inset 0 0 0 3px white;
      }
    }

    &[data-selection-start] {
      border-start-start-radius: 6px;
      border-end-start-radius: 6px;
    }

    &[data-selection-end] {
      border-start-end-radius: 6px;
      border-end-end-radius: 6px;
    }

    &[data-disabled] {
      color: var(--spectrum-global-color-gray-600); 
    }

    &[data-unavailable] {
      text-decoration: line-through;
      color: var(--spectrum-global-color-red-600);
    }

    &[aria-invalid] {
      background: var(--spectrum-global-color-static-red-600);
      color: white;
    }
  }

  & [slot=errorMessage] {
    font-size: 12px;
    color: var(--spectrum-global-color-red-600);
  }
}

.react-aria-DateRangePicker {
  & [role=group] {
    display: flex;
    align-items: center;
    width: fit-content;
    min-width: 220px;
    padding: 2px 2px 2px 8px;
    border: 1px solid var(--spectrum-global-color-gray-400);
    border-radius: 6px;
    background: var(--spectrum-global-color-gray-50);

    &:focus-within {
      border-color: slateblue;
      box-shadow: 0 0 0 1px slateblue;
    }
  }

  & [slot=start] + span {
    padding: 0 4px;
  }

  & [slot=end] {
    margin-right: 2rem;
    flex: 1;
  }

  & button {
    background: slateblue;
    color: white;
    border-radius: 4px;
    border: none;
    appearance: none;
    margin-left: auto;
    width: 1.429rem;
    height: 1.429rem;
    padding: 0;
    vertical-align: middle;
    font-size: 0.857rem;
    outline: none;
    box-sizing: content-box;
    border: 2px solid var(--page-background);

    &[data-focus-visible] {
      box-shadow: 0 0 0 2px slateblue;
    }
  }

  & [slot=description] {
    font-size: 12px;
  }

  & [slot=errorMessage] {
    font-size: 12px;
    color: var(--spectrum-global-color-red-600);
  }
}

.react-aria-DateInput {
  display: flex;
}

.react-aria-DateSegment {
  padding: 0 2px;
  font-variant-numeric: tabular-nums;
  text-align: end;

  &[data-type=literal] {
    padding: 0;
  }

  &[data-placeholder] {
    color: var(--spectrum-global-color-gray-700);
    font-style: italic;
  }

  &:focus {
    color: white;
    background: slateblue;
    outline: none;
    border-radius: 4px;
    caret-color: transparent;
  }

  &[aria-invalid] {
    color: var(--spectrum-global-color-red-600);

    &:focus {
      background: var(--spectrum-global-color-static-red-600);
      color: white;
    }
  }
}

.react-aria-Popover {
  overflow: auto;
  border: 1px solid var(--spectrum-global-color-gray-400);
  box-shadow: 0 8px 20px rgba(0 0 0 / 0.1);
  border-radius: 6px;
  background: var(--page-background);
  padding: 1.25rem;
}

.react-aria-RangeCalendar {
  width: fit-content;

  & header {
    display: flex;
    align-items: center;
    margin-bottom: .5rem;

    & h2 {
      flex: 1;
      margin: 0;
      text-align: center;
      font-size: 1.375rem;
    }

    & button {
      background: var(--spectrum-global-color-gray-50);
      border: 1px solid var(--spectrum-global-color-gray-400);
      box-shadow: 0 1px 2px rgba(0 0 0 / 0.1);
      border-radius: 4px;
      appearance: none;
      vertical-align: middle;
      font-size: 1rem;
      width: 1.75rem;
      height: 1.75rem;
      text-align: center;
      margin: 0;
      outline: none;

      &[data-focus-visible] {
        border-color: slateblue;
        box-shadow: 0 0 0 1px slateblue;
      }

      &[data-pressed] {
        background: var(--spectrum-global-color-gray-100);
      }
    }
  }

  & table {
    margin: 0 -4px;
    border-collapse: collapse;

    & td {
      padding: 2px 0;
    }
  }

  & .react-aria-CalendarCell {
    width: 2.286rem;
    line-height: 2.286rem;
    text-align: center;
    border-radius: 6px;
    cursor: default;
    outline: none;

    &[data-outside-month] {
      display: none;
    }

    &[data-pressed] {
      background: var(--spectrum-global-color-gray-200);
    }

    &[data-focus-visible] {
      box-shadow: inset 0 0 0 2px slateblue;
    }

    &[data-selected] {
      background: slateblue;
      color: white;
      border-radius: 0;

      &[data-focus-visible] {
        box-shadow: inset 0 0 0 1px slateblue, inset 0 0 0 3px white;
      }
    }

    &[data-selection-start] {
      border-start-start-radius: 6px;
      border-end-start-radius: 6px;
    }

    &[data-selection-end] {
      border-start-end-radius: 6px;
      border-end-end-radius: 6px;
    }

    &[data-disabled] {
      color: var(--spectrum-global-color-gray-600); 
    }

    &[data-unavailable] {
      text-decoration: line-through;
      color: var(--spectrum-global-color-red-600);
    }

    &[aria-invalid] {
      background: var(--spectrum-global-color-static-red-600);
      color: white;
    }
  }

  & [slot=errorMessage] {
    font-size: 12px;
    color: var(--spectrum-global-color-red-600);
  }
}

Features#

A date range picker can be built using two separate <input type="date"> elements, but this is very limited in functionality, lacking in internationalization capabilities, inconsistent between browsers, and difficult to style. DateRangePicker helps achieve accessible and international date and time range pickers that can be styled as needed.

Dates and times – Support for dates and times with configurable granularity.
International – Support for 13 calendar systems used around the world, including Gregorian, Buddhist, Islamic, Persian, and more. Locale-specific formatting, number systems, hour cycles, and right-to-left support are available as well.
Time zone aware – Dates and times can optionally include a time zone. All modifications follow time zone rules such as daylight saving time.
Accessible – Each date and time unit is displayed as an individually focusable and editable segment, which allows users an easy way to edit dates using the keyboard, in any date format and locale. Users can also open a calendar popover to select date ranges in a standard month grid. Localized screen reader messages are included to announce when the selection and visible date range change.
Touch friendly – Date segments are editable using an easy to use numeric keypad, date ranges can be selected by dragging over dates in the calendar using a touch screen, and all interactions are accessible using touch-based screen readers.
Customizable – As with all of React Aria, the DOM structure and styling of all elements can be fully customized.

Read our blog post for more details about the internationalization, accessibility, and user experience features implemented by DateRangePicker.

Anatomy#

A date picker consists of a label, and group containing a date field and a button. Clicking the button opens a popup containing a calendar. The date field includes segments representing each unit of a date and time (e.g. years, months, days, etc.), each of which is individually focusable and editable using the keyboard. The calendar popup offers a more visual way of choosing a date.

DateRangePicker also supports optional description and error message elements, which can be used to provide more context about the field, and any validation messages. These are linked with the input via the aria-describedby attribute.

If the date range picker does not have a visible label, an aria-label or aria-labelledby prop must be passed instead to identify it to assistive technology.

Note that most of this anatomy is shared with DatePicker, so you can reuse many components between them if you have both.

Concepts#

DateRangePicker makes use of the following concepts:

@internationalized/date

Composed components#

A DateRangePicker uses the following components, which may also be used standalone or reused in other components.

Label

A label provides context for an input element.

DateField

A date field allows a user to enter and edit date values using a keyboard.

Button

A button allows a user to perform an action.

Popover

A popover displays content in context with a trigger element.

Dialog

A dialog is an overlay shown above other content in an application.

RangeCalendar

A range calendar allows a user to select a contiguous range of dates.

Props#

DateRangePicker#

Name	Type	Default	Description
`minValue`	`DateValue`	—	The minimum allowed date that a user may select.
`maxValue`	`DateValue`	—	The maximum allowed date that a user may select.
`isDateUnavailable`	`( (date: DateValue )) => boolean`	—	Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
`placeholderValue`	`DateValue`	—	A placeholder date that influences the format of the placeholder shown when no value is selected. Defaults to today's date at midnight.
`hourCycle`	`12 \| 24`	—	Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale.
`granularity`	`Granularity`	—	Determines the smallest unit that is displayed in the date picker. By default, this is `"day"` for dates, and `"minute"` for times.
`hideTimeZone`	`boolean`	`false`	Whether to hide the time zone abbreviation.
`isDisabled`	`boolean`	—	Whether the input is disabled.
`isReadOnly`	`boolean`	—	Whether the input can be selected but not changed by the user.
`validationState`	`ValidationState`	—	Whether the input should display its "valid" or "invalid" visual styling.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission. Often paired with the `necessityIndicator` prop to add a visual indicator to the input.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`isOpen`	`boolean`	—	Whether the overlay is open by default (controlled).
`defaultOpen`	`boolean`	—	Whether the overlay is open by default (uncontrolled).
`allowsNonContiguousRanges`	`boolean`	—	When combined with `isDateUnavailable`, determines whether non-contiguous ranges, i.e. ranges containing unavailable dates, may be selected.
`value`	`RangeValue<DateValue>`	—	The current value (controlled).
`defaultValue`	`RangeValue<DateValue>`	—	The default value (uncontrolled).
`children`	`ReactNode \| ( (values: DateRangePickerState )) => ReactNode`	—
`className`	`string \| ( (values: DateRangePickerState )) => string`	—
`style`	`CSSProperties \| ( (values: DateRangePickerState )) => CSSProperties`	—

Events

Name	Type	Default	Description
`onFocus`	`( (e: FocusEvent )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is released.
`onOpenChange`	`( (isOpen: boolean )) => void`	—	Handler that is called when the overlay's open state changes.
`onChange`	`( (value: RangeValue<MappedDateValue<DateValue>> )) => void`	—	Handler that is called when the value changes.

Accessibility

Name	Type	Default	Description
`id`	`string`	—	The element's unique identifier. See MDN.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.

Label#

A <Label> accepts all HTML attributes.

Group#

A <Group> accepts all HTML attributes.

DateInput#

The <DateInput> component renders a group of date segments. It accepts a function as its children, which is called to render a <DateSegment> for each segment. The slot="start" and slot="end" props distinguish the two instances within a DateRangePicker.

Show props

Name	Type	Default	Description
`children`	`( (segment: DateSegment )) => ReactElement`	—
`className`	`string`	—
`style`	`CSSProperties`	—

Layout

Name	Type	Default	Description
`slot`	`string`	—

DateSegment#

The <DateSegment> component renders an individual segment.

Show props

Name	Type	Default	Description
`segment`	`DateSegment`	—
`children`	`ReactNode \| ( (values: DateSegmentRenderProps )) => ReactNode`	—
`className`	`string \| ( (values: DateSegmentRenderProps )) => string`	—
`style`	`CSSProperties \| ( (values: DateSegmentRenderProps )) => CSSProperties`	—

Button#

A <Button> accepts its contents as children. Other props such as onPress and isDisabled will be set by the DateRangePicker or RangeCalendar.

Show props

Name	Type	Default	Description
`isDisabled`	`boolean`	—	Whether the button is disabled.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`type`	`'button' \| 'submit' \| 'reset'`	`'button'`	The behavior of the button when used in an HTML form.
`children`	`ReactNode \| ( (values: ButtonRenderProps )) => ReactNode`	—
`className`	`string \| ( (values: ButtonRenderProps )) => string`	—
`style`	`CSSProperties \| ( (values: ButtonRenderProps )) => CSSProperties`	—

Events

Name	Type	Default	Description
`onPress`	`( (e: PressEvent )) => void`	—	Handler that is called when the press is released over the target.
`onPressStart`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction starts.
`onPressEnd`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
`onPressChange`	`( (isPressed: boolean )) => void`	—	Handler that is called when the press state changes.
`onPressUp`	`( (e: PressEvent )) => void`	—	Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
`onFocus`	`( (e: FocusEvent )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is released.

Layout

Name	Type	Default	Description
`slot`	`string`	—

Accessibility

Name	Type	Default	Description
`id`	`string`	—	The element's unique identifier. See MDN.
`excludeFromTabOrder`	`boolean`	—	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
`aria-expanded`	`boolean \| 'true' \| 'false'`	—	Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
`aria-haspopup`	`boolean \| 'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog' \| 'true' \| 'false'`	—	Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
`aria-controls`	`string`	—	Identifies the element (or elements) whose contents or presence are controlled by the current element.
`aria-pressed`	`boolean \| 'true' \| 'false' \| 'mixed'`	—	Indicates the current "pressed" state of toggle buttons.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.

A <Popover> is an overlay to hold the <Calendar>, positioned relative to the <Group>. By default, it has a placement of bottom start within a <DateRangePicker>, but this and other positioning properties may be customized.

Show props

Name	Type	Default	Description
`triggerRef`	`RefObject<Element>`	—	The ref for the element which the popover positions itself with respect to. When used within a trigger component such as DialogTrigger, MenuTrigger, Select, etc., this is set automatically. It is only required when used standalone.
`placement`	`Placement`	`'bottom'`	The placement of the element with respect to its anchor element.
`containerPadding`	`number`	`12`	The placement padding that should be applied between the element and its surrounding container.
`offset`	`number`	`0`	The additional offset applied along the main axis between the element and its anchor element.
`crossOffset`	`number`	`0`	The additional offset applied along the cross axis between the element and its anchor element.
`shouldFlip`	`boolean`	`true`	Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely.
`isNonModal`	`boolean`	—	Whether the popover is non-modal, i.e. elements outside the popover may be interacted with by assistive technologies. Most popovers should not use this option as it may negatively impact the screen reader experience. Only use with components such as combobox, which are designed to handle this situation carefully.
`children`	`ReactNode \| ( (values: PopoverRenderProps )) => ReactNode`	—
`className`	`string \| ( (values: PopoverRenderProps )) => string`	—
`style`	`CSSProperties \| ( (values: PopoverRenderProps )) => CSSProperties`	—

Dialog#

A <Dialog> is placed within a <Popover> to hold the <Calendar> for a DateRangePicker.

Show props

Name	Type	Default	Description
`children`	`ReactNode`	—
`className`	`string`	—
`style`	`CSSProperties`	—

Events

Name	Type	Default	Description
`onClose`	`() => void`	—

Accessibility

Name	Type	Default	Description
`role`	`'dialog' \| 'alertdialog'`	`'dialog'`	The accessibility role for the dialog.
`id`	`string`	—	The element's unique identifier. See MDN.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.

RangeCalendar#

A <RangeCalendar> accepts one or more month grids as chilren, along with previous and next buttons to navigate forward and backward.

Show props

Name	Type	Default	Description
`visibleDuration`	`DateDuration`	`{months: 1}`	The amount of days that will be displayed at once. This affects how pagination works.
`minValue`	`DateValue`	—	The minimum allowed date that a user may select.
`maxValue`	`DateValue`	—	The maximum allowed date that a user may select.
`isDateUnavailable`	`( (date: DateValue )) => boolean`	—	Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
`isDisabled`	`boolean`	`false`	Whether the calendar is disabled.
`isReadOnly`	`boolean`	`false`	Whether the calendar value is immutable.
`autoFocus`	`boolean`	`false`	Whether to automatically focus the calendar when it mounts.
`focusedValue`	`DateValue`	—	Controls the currently focused date within the calendar.
`defaultFocusedValue`	`DateValue`	—	The date that is focused when the calendar first mounts (uncountrolled).
`validationState`	`ValidationState`	—	Whether the current selection is valid or invalid according to application logic.
`value`	`DateValue`	—	The current value (controlled).
`defaultValue`	`DateValue`	—	The default value (uncontrolled).
`children`	`ReactNode \| ( (values: CalendarState )) => ReactNode`	—
`className`	`string \| ( (values: CalendarState )) => string`	—
`style`	`CSSProperties \| ( (values: CalendarState )) => CSSProperties`	—

Events

Name	Type	Default	Description
`onFocusChange`	`( (date: CalendarDate )) => void`	—	Handler that is called when the focused date changes.
`onChange`	`( (value: MappedDateValue<DateValue> )) => void`	—	Handler that is called when the value changes.

CalendarGrid#

A <CalendarGrid> renders an individual month within a <RangeCalendar>. It accepts a function as its children, which is called to render a <CalendarCell> for each date.

Show props

Name	Type	Default	Description
`children`	`( (date: CalendarDate )) => ReactElement`	—
`offset`	`DateDuration`	—
`className`	`string`	—
`style`	`CSSProperties`	—

CalendarCell#

A <CalendarCell> renders an individual date within a <CalendarGrid>.

Show props

Name	Type	Default	Description
`date`	`CalendarDate`	—
`children`	`ReactNode \| ( (values: CalendarCellRenderProps )) => ReactNode`	—
`className`	`string \| ( (values: CalendarCellRenderProps )) => string`	—
`style`	`CSSProperties \| ( (values: CalendarCellRenderProps )) => CSSProperties`	—

Styling#

React Aria components can be styled in many ways, including using CSS classes, inline styles, utility classes (e.g. Tailwind), CSS-in-JS (e.g. Styled Components), etc. By default, all components include a builtin className attribute which can be targeted using CSS selectors. These follow the react-aria-ComponentName naming convention.

.react-aria-DateRangePicker {
  /* ... */
}

.react-aria-DateRangePicker {
  /* ... */
}

.react-aria-DateRangePicker {
  /* ... */
}

A custom className can also be specified on any component. This overrides the default className provided by React Aria with your own.

<DateInput className="my-date-input">
  {/* ... */}
</DateInput>

<DateInput className="my-date-input">
  {/* ... */}
</DateInput>

<DateInput className="my-date-input">
  {/* ... */}
</DateInput>;

In addition, some components support multiple UI states (e.g. focused, placeholder, readonly, etc.). React Aria components expose states using DOM attributes, which you can target in CSS selectors. These are ARIA attributes wherever possible, or data attributes when a relevant ARIA attribute does not exist. For example:

.react-aria-DateSegment[data-placeholder] {
  /* ... */
}

.react-aria-DateSegment[aria-readonly] {
  /* ... */
}

.react-aria-DateSegment[data-placeholder] {
  /* ... */
}

.react-aria-DateSegment[aria-readonly] {
  /* ... */
}

.react-aria-DateSegment[data-placeholder] {
  /* ... */
}

.react-aria-DateSegment[aria-readonly] {
  /* ... */
}

The className and style props also accept functions which receive states for styling. This lets you dynamically determine the classes or styles to apply, which is useful when using utility CSS libraries like Tailwind.

<DateSegment
  className={({ isPlaceholder }) =>
    isPlaceholder ? 'bg-gray-300' : 'bg-gray-600'}
/>;

<DateSegment
  className={({ isPlaceholder }) =>
    isPlaceholder ? 'bg-gray-300' : 'bg-gray-600'}
/>;

<DateSegment
  className={(
    { isPlaceholder }
  ) =>
    isPlaceholder
      ? 'bg-gray-300'
      : 'bg-gray-600'}
/>;

Render props may also be used as children to alter what elements are rendered based on the current state. For example, you could render the placeholder as a separate element to always reserve space for it.

<DateSegment>
  {({ text, placeholder, isPlaceholder }) => (
    <>
      <span style={{ visibility: isPlaceholder ? 'visible' : 'hidden' }}>
        {placeholder}
      </span>
      {isPlaceholder ? '' : text}
    </>
  )}
</DateSegment>;

<DateSegment>
  {({ text, placeholder, isPlaceholder }) => (
    <>
      <span
        style={{
          visibility: isPlaceholder ? 'visible' : 'hidden'
        }}
      >
        {placeholder}
      </span>
      {isPlaceholder ? '' : text}
    </>
  )}
</DateSegment>;

<DateSegment>
  {(
    {
      text,
      placeholder,
      isPlaceholder
    }
  ) => (
    <>
      <span
        style={{
          visibility:
            isPlaceholder
              ? 'visible'
              : 'hidden'
        }}
      >
        {placeholder}
      </span>
      {isPlaceholder
        ? ''
        : text}
    </>
  )}
</DateSegment>;

The states, selectors, and render props for each component used in a DateRangePicker are documented below.

DateRangePicker#

A DateRangePicker can be targeted with the .react-aria-DateRangePicker CSS selector, or by overriding with a custom className. It provides a DateRangePickerState object to its render props, which can be used to customize the className, style, or children.

Label#

A Label can be targeted with the .react-aria-Label CSS selector, or by overriding with a custom className.

Group#

A Group can be targeted with the [role=group] selector, or by adding a custom className.

DateInput#

A DateInput can be targeted with the .react-aria-DateInput CSS selector, or by overriding with a custom className.

DateSegment#

A DateSegment can be targeted with the .react-aria-DateSegment CSS selector, or by overriding with a custom className. It supports the following states and render props:

Name	CSS Selector	Description
`isPlaceholder`	`[data-placeholder]`	Whether the value is a placeholder.
`isReadOnly`	`[aria-readonly]`	Whether the segment is read only.
`isInvalid`	`[aria-invalid]`	Whether the date field is in an invalid state.
`type`	`[data-type="..."]`	The type of segment. Values include `literal`, `year`, `month`, `day`, etc.
`text`	`—`	The formatted text for the segment.
`value`	`—`	The numeric value for the segment, if applicable.
`minValue`	`—`	The minimum numeric value for the segment, if applicable.
`maxValue`	`—`	The maximum numeric value for the segment, if applicable.
`placeholder`	`—`	A placeholder string for the segment.

Button#

A Button can be targeted with the .react-aria-Button CSS selector, or by overriding with a custom className. The next and previous buttons within a range calendar can be targeted specifically with the [slot=previous] and [slot=next] selectors. Buttons support the following states:

Name	CSS Selector	Description
`isHovered`	`[data-hovered]`	Whether the button is currently hovered with a mouse.
`isPressed`	`[data-pressed]`	Whether the button is currently in a pressed state.
`isFocused`	`:focus`	Whether the button is focused, either via a mouse or keyboard.
`isFocusVisible`	`[data-focus-visible]`	Whether the button is keyboard focused.
`isDisabled`	`:disabled`	Whether the button is disabled.

The Popover component can be targeted with the .react-aria-Popover CSS selector, or by overriding with a custom className. Note that it renders in a React Portal, so it will not appear as a descendant of the DateRangePicker in the DOM. It supports the following states and render props:

Name	CSS Selector	Description
`placement`	`[data-placement="left \| right \| top \| bottom"]`	The placement of the tooltip relative to the trigger.
`isEntering`	`[data-entering]`	Whether the popover is currently entering. Use this to apply animations.
`isExiting`	`[data-exiting]`	Whether the popover is currently exiting. Use this to apply animations.

Dialog#

A Dialog can be targeted with the .react-aria-Dialog CSS selector, or by overriding with a custom className.

RangeCalendar#

A RangeCalendar can be targeted with the .react-aria-RangeCalendar CSS selector, or by overriding with a custom className.

CalendarGrid#

A CalendarGrid can be targeted with the .react-aria-CalendarGrid CSS selector, or by overriding with a custom className.

CalendarCell#

A CalendarCell can be targeted with the .react-aria-CalendarCell CSS selector, or by overriding with a custom className. It supports the following states:

Name	CSS Selector	Description
`date`	`—`	The date that the cell represents.
`formattedDate`	`—`	The day number formatted according to the current locale.
`isHovered`	`[data-hovered]`	Whether the cell is currently hovered with a mouse.
`isPressed`	`[data-pressed]`	Whether the cell is currently being pressed.
`isSelected`	`[data-selected]`	Whether the cell is selected.
`isSelectionStart`	`[data-selection-start]`	Whether the cell is the first date in a range selection.
`isSelectionEnd`	`[data-selection-end]`	Whether the cell is the last date in a range selection.
`isFocused`	`:focus`	Whether the cell is focused.
`isFocusVisible`	`[data-focus-visible]`	Whether the cell is keyboard focused.
`isDisabled`	`[data-disabled]`	Whether the cell is disabled, according to the calendar's `minValue`, `maxValue`, and `isDisabled` props. Disabled dates are not focusable, and cannot be selected by the user. They are typically displayed with a dimmed appearance.
`isOutsideVisibleRange`	`[data-outside-visible-range]`	Whether the cell is outside the visible range of the calendar. For example, dates before the first day of a month in the same week.
`isOutsideMonth`	`[data-outside-month]`	Whether the cell is outside the current month.
`isUnavailable`	`[data-unavailable]`	Whether the cell is unavailable, according to the calendar's `isDateUnavailable` prop. Unavailable dates remain focusable, but cannot be selected by the user. They should be displayed with a visual affordance to indicate they are unavailable, such as a different color or a strikethrough. Note that because they are focusable, unavailable dates must meet a 4.5:1 color contrast ratio, as defined by WCAG.
`isInvalid`	`[aria-invalid]`	Whether the cell is part of an invalid selection.

Text#

The help text elements within a DateRangePicker can be targeted with the [slot=description] and [slot=errorMessage] CSS selectors, or by adding a custom className.

Reusable wrappers#

If you will use a DateRangePicker in multiple places in your app, you can wrap all of the pieces into a reusable component. This way, the DOM structure, styling code, and other logic are defined in a single place and reused everywhere to ensure consistency.

This example wraps DateRangePicker and all of its children together into a single component which accepts a label prop, which is passed to the right place. It also shows how to use the description and errorMessage slots to render help text (see below for details).

import {Text} from 'react-aria-components';

function MyDateRangePicker({label, description, errorMessage, ...props}) {
  return (
    <DateRangePicker {...props}>
      <Label>{label}</Label>
      <Group>
        <DateInput slot="start">
          {segment => <DateSegment segment={segment} />}
        </DateInput>
        <span aria-hidden="true">–</span>
        <DateInput slot="end">
          {segment => <DateSegment segment={segment} />}
        </DateInput>
        <Button>▼</Button>
      </Group>
      {description && <Text slot="description">{description}</Text>}
      {errorMessage && <Text slot="errorMessage">{errorMessage}</Text>}
      <Popover>
        <Dialog>
          <RangeCalendar>
            <header>
              <Button slot="previous">◀</Button>
              <Heading />
              <Button slot="next">▶</Button>
            </header>
            <CalendarGrid>
              {date => <CalendarCell date={date} />}
            </CalendarGrid>
            {errorMessage && <Text slot="errorMessage">{errorMessage}</Text>}
          </RangeCalendar>
        </Dialog>
      </Popover>
    </DateRangePicker>
  );
}

<MyDateRangePicker label="Event date" />

import {Text} from 'react-aria-components';

function MyDateRangePicker(
  { label, description, errorMessage, ...props }
) {
  return (
    <DateRangePicker {...props}>
      <Label>{label}</Label>
      <Group>
        <DateInput slot="start">
          {(segment) => <DateSegment segment={segment} />}
        </DateInput>
        <span aria-hidden="true">–</span>
        <DateInput slot="end">
          {(segment) => <DateSegment segment={segment} />}
        </DateInput>
        <Button>▼</Button>
      </Group>
      {description && (
        <Text slot="description">{description}</Text>
      )}
      {errorMessage && (
        <Text slot="errorMessage">{errorMessage}</Text>
      )}
      <Popover>
        <Dialog>
          <RangeCalendar>
            <header>
              <Button slot="previous">◀</Button>
              <Heading />
              <Button slot="next">▶</Button>
            </header>
            <CalendarGrid>
              {(date) => <CalendarCell date={date} />}
            </CalendarGrid>
            {errorMessage && (
              <Text slot="errorMessage">
                {errorMessage}
              </Text>
            )}
          </RangeCalendar>
        </Dialog>
      </Popover>
    </DateRangePicker>
  );
}

<MyDateRangePicker label="Event date" />

import {Text} from 'react-aria-components';

function MyDateRangePicker(
  {
    label,
    description,
    errorMessage,
    ...props
  }
) {
  return (
    <DateRangePicker
      {...props}
    >
      <Label>
        {label}
      </Label>
      <Group>
        <DateInput slot="start">
          {(segment) => (
            <DateSegment
              segment={segment}
            />
          )}
        </DateInput>
        <span aria-hidden="true">
          –
        </span>
        <DateInput slot="end">
          {(segment) => (
            <DateSegment
              segment={segment}
            />
          )}
        </DateInput>
        <Button>
          ▼
        </Button>
      </Group>
      {description && (
        <Text slot="description">
          {description}
        </Text>
      )}
      {errorMessage && (
        <Text slot="errorMessage">
          {errorMessage}
        </Text>
      )}
      <Popover>
        <Dialog>
          <RangeCalendar>
            <header>
              <Button slot="previous">
                ◀
              </Button>
              <Heading />
              <Button slot="next">
                ▶
              </Button>
            </header>
            <CalendarGrid>
              {(date) => (
                <CalendarCell
                  date={date}
                />
              )}
            </CalendarGrid>
            {errorMessage &&
              (
                <Text slot="errorMessage">
                  {errorMessage}
                </Text>
              )}
          </RangeCalendar>
        </Dialog>
      </Popover>
    </DateRangePicker>
  );
}

<MyDateRangePicker label="Event date" />

Usage#

The following examples show how to use the MyDateRangePicker component created in the above example.

Value#

A DateRangePicker displays a placeholder by default. An initial, uncontrolled value can be provided to the DateRangePicker using the defaultValue prop. Alternatively, a controlled value can be provided using the value prop.

Date ranges are objects with start and end properties containing date values, which are provided using objects in the @internationalized/date package. This library handles correct international date manipulation across calendars, time zones, and other localization concerns. DateRangePicker supports values of the following types:

CalendarDate – a date without any time components. May be parsed from a string representation using the parseDate function. Use this type to represent dates where the time is not important, such as a birthday or an all day calendar event.
CalendarDateTime – a date with a time, but not in any specific time zone. May be parsed from a string representation using the parseDateTime function. Use this type to represent times that occur at the same local time regardless of the time zone, such as the time of New Years Eve fireworks which always occur at midnight. Most times are better stored as a ZonedDateTime.
ZonedDateTime – a date with a time in a specific time zone. May be parsed from a string representation using the parseZonedDateTime, parseAbsolute, or parseAbsoluteToLocal functions. Use this type to represent an exact moment in time at a particular location on Earth.

import {parseDate} from '@internationalized/date';

function Example() {
  let [value, setValue] = React.useState({
    start: parseDate('2020-02-03'),
    end: parseDate('2020-02-08')
  });

  return (
    <>
      <MyDateRangePicker
        label="Date range (uncontrolled)"
        defaultValue={{
          start: parseDate('2020-02-03'),
          end: parseDate('2020-02-08')
        }} />
      <MyDateRangePicker
        label="Date range (controlled)"
        value={value}
        onChange={setValue} />
    </>
  );
}

import {parseDate} from '@internationalized/date';

function Example() {
  let [value, setValue] = React.useState({
    start: parseDate('2020-02-03'),
    end: parseDate('2020-02-08')
  });

  return (
    <>
      <MyDateRangePicker
        label="Date range (uncontrolled)"
        defaultValue={{
          start: parseDate('2020-02-03'),
          end: parseDate('2020-02-08')
        }} />
      <MyDateRangePicker
        label="Date range (controlled)"
        value={value}
        onChange={setValue} />
    </>
  );
}

import {parseDate} from '@internationalized/date';

function Example() {
  let [value, setValue] =
    React.useState({
      start: parseDate(
        '2020-02-03'
      ),
      end: parseDate(
        '2020-02-08'
      )
    });

  return (
    <>
      <MyDateRangePicker
        label="Date range (uncontrolled)"
        defaultValue={{
          start:
            parseDate(
              '2020-02-03'
            ),
          end: parseDate(
            '2020-02-08'
          )
        }}
      />
      <MyDateRangePicker
        label="Date range (controlled)"
        value={value}
        onChange={setValue}
      />
    </>
  );
}

Events#

DateRangePicker accepts an onChange prop which is triggered whenever the start or end date is edited by the user. The example below uses onChange to update a separate element with a formatted version of the date range in the user's locale and local time zone. This is done by converting the dates to native JavaScript Date objects to pass to the formatter.

import {useDateFormatter} from 'react-aria';
import {getLocalTimeZone} from '@internationalized/date';

function Example() {
  let [range, setRange] = React.useState({
    start: parseDate('2020-07-03'),
    end: parseDate('2020-07-10')
  });
  let formatter = useDateFormatter({ dateStyle: 'long' });

  return (
    <>
      <MyDateRangePicker label="Date range" value={range} onChange={setRange} />
      <p>
        Selected date:{' '}
        {formatter.formatRange(
          range.start.toDate(getLocalTimeZone()),
          range.end.toDate(getLocalTimeZone())
        )}
      </p>
    </>
  );
}

import {useDateFormatter} from 'react-aria';
import {getLocalTimeZone} from '@internationalized/date';

function Example() {
  let [range, setRange] = React.useState({
    start: parseDate('2020-07-03'),
    end: parseDate('2020-07-10')
  });
  let formatter = useDateFormatter({ dateStyle: 'long' });

  return (
    <>
      <MyDateRangePicker
        label="Date range"
        value={range}
        onChange={setRange}
      />
      <p>
        Selected date:{' '}
        {formatter.formatRange(
          range.start.toDate(getLocalTimeZone()),
          range.end.toDate(getLocalTimeZone())
        )}
      </p>
    </>
  );
}

import {useDateFormatter} from 'react-aria';
import {getLocalTimeZone} from '@internationalized/date';

function Example() {
  let [range, setRange] =
    React.useState({
      start: parseDate(
        '2020-07-03'
      ),
      end: parseDate(
        '2020-07-10'
      )
    });
  let formatter =
    useDateFormatter({
      dateStyle: 'long'
    });

  return (
    <>
      <MyDateRangePicker
        label="Date range"
        value={range}
        onChange={setRange}
      />
      <p>
        Selected date:
        {' '}
        {formatter
          .formatRange(
            range.start
              .toDate(
                getLocalTimeZone()
              ),
            range.end
              .toDate(
                getLocalTimeZone()
              )
          )}
      </p>
    </>
  );
}

Time zones#

DateRangePicker is time zone aware when ZonedDateTime objects are provided as the value. In this case, the time zone abbreviation is displayed, and time zone concerns such as daylight saving time are taken into account when the value is manipulated.

In most cases, your data will come from and be sent to a server as an ISO 8601 formatted string. @internationalized/date includes functions for parsing strings in multiple formats into ZonedDateTime objects. Which format you use will depend on what information you need to store.

parseZonedDateTime – This function parses a date with an explicit time zone and optional UTC offset attached (e.g. "2021-11-07T00:45[America/Los_Angeles]" or "2021-11-07T00:45-07:00[America/Los_Angeles]"). This format preserves the maximum amount of information. If the exact local time and time zone that a user selected is important, use this format. Storing the time zone and offset that was selected rather than converting to UTC ensures that the local time is correct regardless of daylight saving rule changes (e.g. if a locale abolishes DST). Examples where this applies include calendar events, reminders, and other times that occur in a particular location.
parseAbsolute – This function parses an absolute date and time that occurs at the same instant at all locations on Earth. It can be represented in UTC (e.g. "2021-11-07T07:45:00Z"), or stored with a particular offset (e.g. "2021-11-07T07:45:00-07:00"). A time zone identifier, e.g. America/Los_Angeles, must be passed, and the result will be converted into that time zone. Absolute times are the best way to represent events that occurred in the past, or future events where an exact time is needed, regardless of time zone.
parseAbsoluteToLocal – This function parses an absolute date and time into the current user's local time zone. It is a shortcut for parseAbsolute, and accepts the same formats.

import {parseZonedDateTime} from '@internationalized/date';

<MyDateRangePicker
  label="Date range"
  defaultValue={{
    start: parseZonedDateTime('2022-11-07T00:45[America/Los_Angeles]'),
    end: parseZonedDateTime('2022-11-08T11:15[America/Los_Angeles]')
  }} />

import {parseZonedDateTime} from '@internationalized/date';

<MyDateRangePicker
  label="Date range"
  defaultValue={{
    start: parseZonedDateTime(
      '2022-11-07T00:45[America/Los_Angeles]'
    ),
    end: parseZonedDateTime(
      '2022-11-08T11:15[America/Los_Angeles]'
    )
  }}
/>

import {parseZonedDateTime} from '@internationalized/date';

<MyDateRangePicker
  label="Date range"
  defaultValue={{
    start:
      parseZonedDateTime(
        '2022-11-07T00:45[America/Los_Angeles]'
      ),
    end:
      parseZonedDateTime(
        '2022-11-08T11:15[America/Los_Angeles]'
      )
  }}
/>

DateRangePicker displays times in the time zone included in the ZonedDateTime object. The above example is always displayed in Pacific Standard Time because the America/Los_Angeles time zone identifier is provided. @internationalized/date includes functions for converting dates between time zones, or parsing a date directly into a specific time zone or the user's local time zone, as shown below.

import {parseAbsoluteToLocal} from '@internationalized/date';

<MyDateRangePicker
  label="Date range"
  defaultValue={{
    start: parseAbsoluteToLocal('2021-11-07T07:45:00Z'),
    end: parseAbsoluteToLocal('2021-11-08T14:25:00Z')
  }}
/>

import {parseAbsoluteToLocal} from '@internationalized/date';

<MyDateRangePicker
  label="Date range"
  defaultValue={{
    start: parseAbsoluteToLocal('2021-11-07T07:45:00Z'),
    end: parseAbsoluteToLocal('2021-11-08T14:25:00Z')
  }}
/>

import {parseAbsoluteToLocal} from '@internationalized/date';

<MyDateRangePicker
  label="Date range"
  defaultValue={{
    start:
      parseAbsoluteToLocal(
        '2021-11-07T07:45:00Z'
      ),
    end:
      parseAbsoluteToLocal(
        '2021-11-08T14:25:00Z'
      )
  }}
/>

Granularity#

The granularity prop allows you to control the smallest unit that is displayed by DateRangePicker. By default, CalendarDate values are displayed with "day" granularity (year, month, and day), and CalendarDateTime and ZonedDateTime values are displayed with "minute" granularity. More granular time values can be displayed by setting the granularity prop to "second".

In addition, when a value with a time is provided but you wish to only display the date, you can set the granularity to "day". This has no effect on the actual value (it still has a time component), only on what fields are displayed. In the following example, two DateRangePickers are synchronized with the same value, but display different granularities.

function Example() {
  let [date, setDate] = React.useState({
    start: parseAbsoluteToLocal('2021-04-07T18:45:22Z'),
    end: parseAbsoluteToLocal('2021-04-08T20:00:00Z')
  });

  return (
    <>
      <MyDateRangePicker
        label="Date and time range"
        granularity="second"
        value={date}
        onChange={setDate} />
      <MyDateRangePicker
        label="Date range"
        granularity="day"
        value={date}
        onChange={setDate} />
    </>
  );
}

function Example() {
  let [date, setDate] = React.useState({
    start: parseAbsoluteToLocal('2021-04-07T18:45:22Z'),
    end: parseAbsoluteToLocal('2021-04-08T20:00:00Z')
  });

  return (
    <>
      <MyDateRangePicker
        label="Date and time range"
        granularity="second"
        value={date}
        onChange={setDate} />
      <MyDateRangePicker
        label="Date range"
        granularity="day"
        value={date}
        onChange={setDate} />
    </>
  );
}

function Example() {
  let [date, setDate] =
    React.useState({
      start:
        parseAbsoluteToLocal(
          '2021-04-07T18:45:22Z'
        ),
      end:
        parseAbsoluteToLocal(
          '2021-04-08T20:00:00Z'
        )
    });

  return (
    <>
      <MyDateRangePicker
        label="Date and time range"
        granularity="second"
        value={date}
        onChange={setDate}
      />
      <MyDateRangePicker
        label="Date range"
        granularity="day"
        value={date}
        onChange={setDate}
      />
    </>
  );
}

If no value or defaultValue prop is passed, then the granularity prop also affects which type of value is emitted from the onChange event. Note that by default, time values will not have a time zone because none was supplied. You can override this by setting the placeholderValue prop explicitly. Values emitted from onChange will use the time zone of the placeholder value.

import {now} from '@internationalized/date';

<MyDateRangePicker
  label="Date range"
  granularity="second" />
<MyDateRangePicker
  label="Date range"
  placeholderValue={now('America/New_York')}
  granularity="second" />

import {now} from '@internationalized/date';

<MyDateRangePicker
  label="Date range"
  granularity="second" />
<MyDateRangePicker
  label="Date range"
  placeholderValue={now('America/New_York')}
  granularity="second" />

import {now} from '@internationalized/date';

<MyDateRangePicker
  label="Date range"
  granularity="second"
/>
<MyDateRangePicker
  label="Date range"
  placeholderValue={now(
    'America/New_York'
  )}
  granularity="second"
/>

International calendars#

DateRangePicker supports selecting dates in many calendar systems used around the world, including Gregorian, Hebrew, Indian, Islamic, Buddhist, and more. Dates are automatically displayed in the appropriate calendar system for the user's locale. The calendar system can be overridden using the Unicode calendar locale extension, passed to the I18nProvider component.

Selected dates passed to onChange always use the same calendar system as the value or defaultValue prop. If no value or defaultValue is provided, then dates passed to onChange are always in the Gregorian calendar since this is the most commonly used. This means that even though the user selects dates in their local calendar system, applications are able to deal with dates from all users consistently.

The below example displays a DateRangePicker in the Hindi language, using the Indian calendar. Dates emitted from onChange are in the Gregorian calendar.

import {I18nProvider} from 'react-aria';

function Example() {
  let [range, setRange] = React.useState(null);
  return (
    <I18nProvider locale="hi-IN-u-ca-indian">
      <MyDateRangePicker label="Date range" value={range} onChange={setRange} />
      <p>Start date: {range?.start.toString()}</p>
      <p>End date: {range?.end.toString()}</p>
    </I18nProvider>
  );
}

import {I18nProvider} from 'react-aria';

function Example() {
  let [range, setRange] = React.useState(null);
  return (
    <I18nProvider locale="hi-IN-u-ca-indian">
      <MyDateRangePicker
        label="Date range"
        value={range}
        onChange={setRange}
      />
      <p>Start date: {range?.start.toString()}</p>
      <p>End date: {range?.end.toString()}</p>
    </I18nProvider>
  );
}

import {I18nProvider} from 'react-aria';

function Example() {
  let [range, setRange] =
    React.useState(null);
  return (
    <I18nProvider locale="hi-IN-u-ca-indian">
      <MyDateRangePicker
        label="Date range"
        value={range}
        onChange={setRange}
      />
      <p>
        Start date:{' '}
        {range?.start
          .toString()}
      </p>
      <p>
        End date:{' '}
        {range?.end
          .toString()}
      </p>
    </I18nProvider>
  );
}

Minimum and maximum values#

The minValue and maxValue props can also be used to perform builtin validation. This prevents the user from selecting dates outside the valid range in the calendar, and marks the date fields as invalid using ARIA. DateRangePicker also validates that the end date is after the start date. You should implement a visual indication that the date range picker is invalid as well.

This example only accepts dates after today.

import {today} from '@internationalized/date';

<MyDateRangePicker
  label="Trip dates"
  minValue={today(getLocalTimeZone())}
  defaultValue={{
    start: parseDate('2022-02-03'),
    end: parseDate('2022-05-03')
  }} />

import {today} from '@internationalized/date';

<MyDateRangePicker
  label="Trip dates"
  minValue={today(getLocalTimeZone())}
  defaultValue={{
    start: parseDate('2022-02-03'),
    end: parseDate('2022-05-03')
  }} />

import {today} from '@internationalized/date';

<MyDateRangePicker
  label="Trip dates"
  minValue={today(
    getLocalTimeZone()
  )}
  defaultValue={{
    start: parseDate(
      '2022-02-03'
    ),
    end: parseDate(
      '2022-05-03'
    )
  }}
/>

Unavailable dates#

DateRangePicker supports marking certain dates as unavailable. These dates remain focusable with the keyboard in the calendar so that navigation is consistent, but cannot be selected by the user. The isDateUnavailable prop accepts a callback that is called to evaluate whether each visible date is unavailable.

Note that by default, users may not select non-contiguous ranges, i.e. ranges that contain unavailable dates within them. Once a start date is selected in the calendar, enabled dates will be restricted to subsequent dates until an unavailable date is hit. While this is handled automatically in the calendar, additional validation logic must be provided to ensure an invalid state is displayed in the date field. This can be achieved using the validationState prop. See below for an example of how to allow non-contiguous ranges.

This example includes multiple unavailable date ranges, e.g. dates when a rental house is not available. The minValue prop is also used to prevent selecting dates before today. The validationState prop is used to mark selected date ranges with unavailable dates in the middle as invalid.

import {useLocale} from 'react-aria';
import {today} from '@internationalized/date';

function Example() {
  let now = today(getLocalTimeZone());
  let disabledRanges = [
    [now, now.add({ days: 5 })],
    [now.add({ days: 14 }), now.add({ days: 16 })],
    [now.add({ days: 23 }), now.add({ days: 24 })]
  ];

  let { locale } = useLocale();
  let isDateUnavailable = (date) =>
    disabledRanges.some((interval) =>
      date.compare(interval[0]) >= 0 && date.compare(interval[1]) <= 0
    );
  let [value, setValue] = React.useState(null);
  let isInvalid = value &&
    disabledRanges.some((interval) =>
      value.end.compare(interval[0]) >= 0 &&
      value.start.compare(interval[1]) <= 0
    );

  return (
    <MyDateRangePicker
      label="Trip dates"
      minValue={today(getLocalTimeZone())}
      isDateUnavailable={isDateUnavailable}
      value={value}
      onChange={setValue}
      validationState={isInvalid ? 'invalid' : null}
    />
  );
}

import {useLocale} from 'react-aria';
import {today} from '@internationalized/date';

function Example() {
  let now = today(getLocalTimeZone());
  let disabledRanges = [
    [now, now.add({ days: 5 })],
    [now.add({ days: 14 }), now.add({ days: 16 })],
    [now.add({ days: 23 }), now.add({ days: 24 })]
  ];

  let { locale } = useLocale();
  let isDateUnavailable = (date) =>
    disabledRanges.some((interval) =>
      date.compare(interval[0]) >= 0 &&
      date.compare(interval[1]) <= 0
    );
  let [value, setValue] = React.useState(null);
  let isInvalid = value &&
    disabledRanges.some((interval) =>
      value.end.compare(interval[0]) >= 0 &&
      value.start.compare(interval[1]) <= 0
    );

  return (
    <MyDateRangePicker
      label="Trip dates"
      minValue={today(getLocalTimeZone())}
      isDateUnavailable={isDateUnavailable}
      value={value}
      onChange={setValue}
      validationState={isInvalid ? 'invalid' : null}
    />
  );
}

import {useLocale} from 'react-aria';
import {today} from '@internationalized/date';

function Example() {
  let now = today(
    getLocalTimeZone()
  );
  let disabledRanges = [
    [
      now,
      now.add({
        days: 5
      })
    ],
    [
      now.add({
        days: 14
      }),
      now.add({
        days: 16
      })
    ],
    [
      now.add({
        days: 23
      }),
      now.add({
        days: 24
      })
    ]
  ];

  let { locale } =
    useLocale();
  let isDateUnavailable =
    (date) =>
      disabledRanges
        .some((
          interval
        ) =>
          date.compare(
              interval[0]
            ) >= 0 &&
          date.compare(
              interval[1]
            ) <= 0
        );
  let [value, setValue] =
    React.useState(null);
  let isInvalid =
    value &&
    disabledRanges.some(
      (interval) =>
        value.end
            .compare(
              interval[0]
            ) >= 0 &&
        value.start
            .compare(
              interval[1]
            ) <= 0
    );

  return (
    <MyDateRangePicker
      label="Trip dates"
      minValue={today(
        getLocalTimeZone()
      )}
      isDateUnavailable={isDateUnavailable}
      value={value}
      onChange={setValue}
      validationState={isInvalid
        ? 'invalid'
        : null}
    />
  );
}

Non-contiguous ranges#

The allowsNonContiguousRanges prop enables a range to be selected even if there are unavailable dates in the middle. The value emitted in the onChange event will still be a single range with a start and end property, but unavailable dates will not be displayed as selected. It is up to applications to split the full selected range into multiple as needed for business logic.

This example prevents selecting weekends, but allows selecting ranges that span multiple weeks.

import {isWeekend} from '@internationalized/date';

function Example() {
  let { locale } = useLocale();

  return (
    <MyDateRangePicker
      label="Time off request"
      isDateUnavailable={(date) => isWeekend(date, locale)}
      allowsNonContiguousRanges
    />
  );
}

import {isWeekend} from '@internationalized/date';

function Example() {
  let { locale } = useLocale();

  return (
    <MyDateRangePicker
      label="Time off request"
      isDateUnavailable={(date) => isWeekend(date, locale)}
      allowsNonContiguousRanges
    />
  );
}

import {isWeekend} from '@internationalized/date';

function Example() {
  let { locale } =
    useLocale();

  return (
    <MyDateRangePicker
      label="Time off request"
      isDateUnavailable={(date) =>
        isWeekend(
          date,
          locale
        )}
      allowsNonContiguousRanges
    />
  );
}

Help text#

The description slot can be used to associate additional help text with a date range picker. Additionally, the errorMessage slot can be used to help the user fix a validation error. It should be combined with the validationState prop to semantically mark the date range picker as invalid for assistive technologies.

This example validates that the selected date range is a maximum of 1 week in duration.

import {today} from '@internationalized/date';

function Example() {
  let [range, setRange] = React.useState({
    start: today(getLocalTimeZone()),
    end: today(getLocalTimeZone()).add({ weeks: 1, days: 3 })
  });
  let isInvalid = range.end.compare(range.start) > 7;

  return (
    <MyDateRangePicker
      label="Trip dates"
      value={range}
      onChange={setRange}
      validationState={isInvalid ? 'invalid' : 'valid'}
      description={isInvalid ? null : 'Select your vacation dates'}
      errorMessage={isInvalid ? 'Maximum stay duration is 1 week' : null} />
  );
}

import {today} from '@internationalized/date';

function Example() {
  let [range, setRange] = React.useState({
    start: today(getLocalTimeZone()),
    end: today(getLocalTimeZone()).add({
      weeks: 1,
      days: 3
    })
  });
  let isInvalid = range.end.compare(range.start) > 7;

  return (
    <MyDateRangePicker
      label="Trip dates"
      value={range}
      onChange={setRange}
      validationState={isInvalid ? 'invalid' : 'valid'}
      description={isInvalid
        ? null
        : 'Select your vacation dates'}
      errorMessage={isInvalid
        ? 'Maximum stay duration is 1 week'
        : null}
    />
  );
}

import {today} from '@internationalized/date';

function Example() {
  let [range, setRange] =
    React.useState({
      start: today(
        getLocalTimeZone()
      ),
      end: today(
        getLocalTimeZone()
      ).add({
        weeks: 1,
        days: 3
      })
    });
  let isInvalid =
    range.end.compare(
      range.start
    ) > 7;

  return (
    <MyDateRangePicker
      label="Trip dates"
      value={range}
      onChange={setRange}
      validationState={isInvalid
        ? 'invalid'
        : 'valid'}
      description={isInvalid
        ? null
        : 'Select your vacation dates'}
      errorMessage={isInvalid
        ? 'Maximum stay duration is 1 week'
        : null}
    />
  );
}

Placeholder value#

When no value is set, a placeholder is shown. The format of the placeholder is influenced by the granularity and placeholderValue props. placeholderValue also controls the default values of each segment when the user first interacts with them, e.g. using the up and down arrow keys, as well as the default month shown in the calendar popover. By default, the placeholderValue is the current date at midnight, but you can set it to a more appropriate value if needed.

import {CalendarDate} from '@internationalized/date';

<MyDateRangePicker
  label="Date range"
  placeholderValue={new CalendarDate(1980, 1, 1)}
/>

import {CalendarDate} from '@internationalized/date';

<MyDateRangePicker
  label="Date range"
  placeholderValue={new CalendarDate(1980, 1, 1)}
/>

import {CalendarDate} from '@internationalized/date';

<MyDateRangePicker
  label="Date range"
  placeholderValue={new CalendarDate(
    1980,
    1,
    1
  )}
/>

Hide time zone#

When ZonedDateTime objects are provided as the value of to DateRangePicker, the time zone abbreviation is displayed by default. However, if this is displayed elsewhere or implicit based on the usecase, it can be hidden using the hideTimeZone option.

<MyDateRangePicker
  label="Date range"
  defaultValue={{
    start: parseZonedDateTime('2022-11-07T10:45[America/Los_Angeles]'),
    end: parseZonedDateTime('2022-11-08T19:45[America/Los_Angeles]')
  }}
  hideTimeZone />

<MyDateRangePicker
  label="Date range"
  defaultValue={{
    start: parseZonedDateTime(
      '2022-11-07T10:45[America/Los_Angeles]'
    ),
    end: parseZonedDateTime(
      '2022-11-08T19:45[America/Los_Angeles]'
    )
  }}
  hideTimeZone
/>

<MyDateRangePicker
  label="Date range"
  defaultValue={{
    start:
      parseZonedDateTime(
        '2022-11-07T10:45[America/Los_Angeles]'
      ),
    end:
      parseZonedDateTime(
        '2022-11-08T19:45[America/Los_Angeles]'
      )
  }}
  hideTimeZone
/>

Hour cycle#

By default, DateRangePicker displays times in either 12 or 24 hour hour format depending on the user's locale. However, this can be overridden using the hourCycle prop if needed for a specific usecase. This example forces the DateRangePicker to use 24-hour time, regardless of the locale.

<MyDateRangePicker
  label="Date range"
  granularity="minute"
  hourCycle={24} />

<MyDateRangePicker
  label="Date range"
  granularity="minute"
  hourCycle={24} />

<MyDateRangePicker
  label="Date range"
  granularity="minute"
  hourCycle={24} />

Advanced customization#

Composition#

If you need to customize one of the components within a DateRangePicker, such as Label or DateSegment, in many cases you can create a wrapper component. This lets you customize the props passed to the component.

function MyDateSegment(props) {
  return <MyDateSegment {...props} className="my-date-segment" />
}

function MyDateSegment(props) {
  return (
    <MyDateSegment {...props} className="my-date-segment" />
  );
}

function MyDateSegment(
  props
) {
  return (
    <MyDateSegment
      {...props}
      className="my-date-segment"
    />
  );
}

Hooks#

If you need to customize things even further, such as accessing internal state or customizing DOM structure, you can drop down to the lower level Hook-based API. DateRangePicker sends props to its child elements via public React contexts for each component. You can use this context to implement replacements for any component, using hooks from react-aria. This allows you to replace only the components you need to customize, and keep using the others.

DateRangePicker uses the following hooks. See the linked documentation for more details.

To replace a component used within a DateRangePicker, create your own component and use the useContextProps hook to merge the local props and ref with the ones sent via context by DateRangePicker. This example shows how you could implement a custom RangeCalendar component that works with DateRangePicker.

import {RangeCalendarContext, useContextProps} from 'react-aria-components';
import {useRangeCalendarState} from 'react-stately';
import {useRangeCalendar} from 'react-aria';

function MyRangeCalendar(props) {
  // Merge local props and ref with props from context.
  let ref = React.useRef();
  [props, ref] = useContextProps(props, ref, CalendarContext);

  // Call useCalendarState and useCalendar.
  let state = useRangeCalendarState({...props});
  let {calendarProps} = useRangeCalendar(props, state, ref);

  // Render stuff
  // ...
}

import {
  RangeCalendarContext,
  useContextProps
} from 'react-aria-components';
import {useRangeCalendarState} from 'react-stately';
import {useRangeCalendar} from 'react-aria';

function MyRangeCalendar(props) {
  // Merge local props and ref with props from context.
  let ref = React.useRef();
  [props, ref] = useContextProps(
    props,
    ref,
    CalendarContext
  );

  // Call useCalendarState and useCalendar.
  let state = useRangeCalendarState({ ...props });
  let { calendarProps } = useRangeCalendar(
    props,
    state,
    ref
  );

  // Render stuff
  // ...
}

import {
  RangeCalendarContext,
  useContextProps
} from 'react-aria-components';
import {useRangeCalendarState} from 'react-stately';
import {useRangeCalendar} from 'react-aria';

function MyRangeCalendar(
  props
) {
  // Merge local props and ref with props from context.
  let ref = React
    .useRef();
  [props, ref] =
    useContextProps(
      props,
      ref,
      CalendarContext
    );

  // Call useCalendarState and useCalendar.
  let state =
    useRangeCalendarState(
      { ...props }
    );
  let { calendarProps } =
    useRangeCalendar(
      props,
      state,
      ref
    );

  // Render stuff
  // ...
}

This also works the other way. If you need to customize DateRangePicker itself, but want to reuse the components it contains, you can do so by providing the necessary contexts. The Provider component is an easier way to send multiple contexts at once. You can look at the DateRangePicker source code for more details on how to set this up.

import {ButtonContext, LabelContext, RangeCalendarContext, useDateRangePicker} from 'react-aria';
import {Provider} from 'react-aria-components';

function MyDateRangePicker(props) {
  // ...
  let ref = useRef(null);
  let {
    labelProps,
    buttonProps,
    calendarProps
    // ...
  } = useDateRangePicker({/* ... */});

  return (
    <Provider
      values={[
        [LabelContext, labelProps],
        [ButtonContext, buttonProps],
        [RangeCalendarContext, calendarProps]
        // ...
      ]}
    >
      {props.children}
    </Provider>
  );
}

import {
  ButtonContext,
  LabelContext,
  RangeCalendarContext,
  useDateRangePicker
} from 'react-aria';
import {Provider} from 'react-aria-components';

function MyDateRangePicker(props) {
  // ...
  let ref = useRef(null);
  let {
    labelProps,
    buttonProps,
    calendarProps
    // ...
  } = useDateRangePicker({/* ... */});

  return (
    <Provider
      values={[
        [LabelContext, labelProps],
        [ButtonContext, buttonProps],
        [RangeCalendarContext, calendarProps]
        // ...
      ]}
    >
      {props.children}
    </Provider>
  );
}

import {
  ButtonContext,
  LabelContext,
  RangeCalendarContext,
  useDateRangePicker
} from 'react-aria';
import {Provider} from 'react-aria-components';

function MyDateRangePicker(
  props
) {
  // ...
  let ref = useRef(null);
  let {
    labelProps,
    buttonProps,
    calendarProps
    // ...
  } = useDateRangePicker(
    {/* ... */}
  );

  return (
    <Provider
      values={[
        [
          LabelContext,
          labelProps
        ],
        [
          ButtonContext,
          buttonProps
        ],
        [
          RangeCalendarContext,
          calendarProps
        ]
        // ...
      ]}
    >
      {props.children}
    </Provider>
  );
}

CalendarDate
  | CalendarDateTime
  | ZonedDateTime

A CalendarDate represents a date without any time components in a specific calendar system.

Properties

Name	Type	Description
`calendar`	`Calendar`	The calendar system associated with this date, e.g. Gregorian.
`era`	`string`	The calendar era for this date, e.g. "BC" or "AD".
`year`	`number`	The year of this date within the era.
`month`	`number`	The month number within the year. Note that some calendar systems such as Hebrew may have a variable number of months per year. Therefore, month numbers may not always correspond to the same month names in different years.
`day`	`number`	The day number within the month.

Methods

Method	Description
`constructor( (...args: any[] )): void`
`copy(): CalendarDate`	Returns a copy of this date.
`add( (duration: DateDuration )): CalendarDate`	Returns a new `CalendarDate` with the given duration added to it.
`subtract( (duration: DateDuration )): CalendarDate`	Returns a new `CalendarDate` with the given duration subtracted from it.
`set( (fields: DateFields )): CalendarDate`	Returns a new `CalendarDate` with the given fields set to the provided values. Other fields will be constrained accordingly.
`cycle( field: DateField, amount: number, options?: CycleOptions ): CalendarDate`	Returns a new `CalendarDate` with the given field adjusted by a specified amount. When the resulting value reaches the limits of the field, it wraps around.
`toDate( (timeZone: string )): Date`	Converts the date to a native JavaScript Date object, with the time set to midnight in the given time zone.
`toString(): string`	Converts the date to an ISO 8601 formatted string.
`compare( (b: AnyCalendarDate )): number`	Compares this date with another. A negative result indicates that this date is before the given one, and a positive date indicates that it is after.

A CalendarDateTime represents a date and time without a time zone, in a specific calendar system.

Properties

Name	Type	Description
`calendar`	`Calendar`	The calendar system associated with this date, e.g. Gregorian.
`era`	`string`	The calendar era for this date, e.g. "BC" or "AD".
`year`	`number`	The year of this date within the era.
`month`	`number`	The month number within the year. Note that some calendar systems such as Hebrew may have a variable number of months per year. Therefore, month numbers may not always correspond to the same month names in different years.
`day`	`number`	The day number within the month.
`hour`	`number`	The hour in the day, numbered from 0 to 23.
`minute`	`number`	The minute in the hour.
`second`	`number`	The second in the minute.
`millisecond`	`number`	The millisecond in the second.

Methods

Method	Description
`constructor( (...args: any[] )): void`
`copy(): CalendarDateTime`	Returns a copy of this date.
`add( (duration: DateTimeDuration )): CalendarDateTime`	Returns a new `CalendarDateTime` with the given duration added to it.
`subtract( (duration: DateTimeDuration )): CalendarDateTime`	Returns a new `CalendarDateTime` with the given duration subtracted from it.
`set( (fields: DateFields & & TimeFields )): CalendarDateTime`	Returns a new `CalendarDateTime` with the given fields set to the provided values. Other fields will be constrained accordingly.
`cycle( field: DateField \| \| TimeField, amount: number, options?: CycleTimeOptions ): CalendarDateTime`	Returns a new `CalendarDateTime` with the given field adjusted by a specified amount. When the resulting value reaches the limits of the field, it wraps around.
`toDate( (timeZone: string, , disambiguation?: Disambiguation )): Date`	Converts the date to a native JavaScript Date object in the given time zone.
`toString(): string`	Converts the date to an ISO 8601 formatted string.
`compare( (b: CalendarDate \| CalendarDateTime \| ZonedDateTime )): number`	Compares this date with another. A negative result indicates that this date is before the given one, and a positive date indicates that it is after.

A ZonedDateTime represents a date and time in a specific time zone and calendar system.

Properties

Name	Type	Description
`calendar`	`Calendar`	The calendar system associated with this date, e.g. Gregorian.
`era`	`string`	The calendar era for this date, e.g. "BC" or "AD".
`year`	`number`	The year of this date within the era.
`month`	`number`	The month number within the year. Note that some calendar systems such as Hebrew may have a variable number of months per year. Therefore, month numbers may not always correspond to the same month names in different years.
`day`	`number`	The day number within the month.
`hour`	`number`	The hour in the day, numbered from 0 to 23.
`minute`	`number`	The minute in the hour.
`second`	`number`	The second in the minute.
`millisecond`	`number`	The millisecond in the second.
`timeZone`	`string`	The IANA time zone identifier that this date and time is represented in.
`offset`	`number`	The UTC offset for this time, in seconds.

Methods

Method	Description
`constructor( (...args: any[] )): void`
`copy(): ZonedDateTime`	Returns a copy of this date.
`add( (duration: DateTimeDuration )): void`	Returns a new `ZonedDateTime` with the given duration added to it.
`subtract( (duration: DateTimeDuration )): void`	Returns a new `ZonedDateTime` with the given duration subtracted from it.
`set( (fields: DateFields & & TimeFields, , disambiguation?: Disambiguation )): void`	Returns a new `ZonedDateTime` with the given fields set to the provided values. Other fields will be constrained accordingly.
`cycle( field: DateField \| \| TimeField, amount: number, options?: CycleTimeOptions ): void`	Returns a new `ZonedDateTime` with the given field adjusted by a specified amount. When the resulting value reaches the limits of the field, it wraps around.
`toDate(): void`	Converts the date to a native JavaScript Date object.
`toString(): void`	Converts the date to an ISO 8601 formatted string, including the UTC offset and time zone identifier.
`toAbsoluteString(): void`	Converts the date to an ISO 8601 formatted string in UTC.
`compare( (b: CalendarDate \| CalendarDateTime \| ZonedDateTime )): void`	Compares this date with another. A negative result indicates that this date is before the given one, and a positive date indicates that it is after.

'day'
  | 'hour'
  | 'minute'
  | 'second'

'valid' | 'invalid'

Name	Type	Description
`start`	`T`	The start value of the range.
`end`	`T`	The end value of the range.

Properties

Name	Type	Description
`value`	`DateRange`	The currently selected date range.
`dateRange`	`DateRange`	The date portion of the selected range. This may be set prior to `value` if the user has selected a date range but has not yet selected a time range.
`timeRange`	`TimeRange`	The time portion of the selected range. This may be set prior to `value` if the user has selected a time range but has not yet selected a date range.
`granularity`	`Granularity`	The granularity for the field, based on the `granularity` prop and current value.
`hasTime`	`boolean`	Whether the date range picker supports selecting times, according to the `granularity` prop and current value.
`isOpen`	`boolean`	Whether the calendar popover is currently open.
`validationState`	`ValidationState`	The current validation state of the date picker, based on the `validationState`, `minValue`, and `maxValue` props.

Methods

Method	Description
`setValue( (value: DateRange )): void`	Sets the selected date range.
`setDateRange( (value: DateRange )): void`	Sets the date portion of the selected range.
`setTimeRange( (value: TimeRange )): void`	Sets the time portion of the selected range.
`setDate( (part: 'start' \| \| 'end', , value: DateValue )): void`	Sets the date portion of either the start or end of the selected range.
`setTime( (part: 'start' \| \| 'end', , value: TimeValue )): void`	Sets the time portion of either the start or end of the selected range.
`setDateTime( (part: 'start' \| \| 'end', , value: DateValue )): void`	Sets the date and time of either the start or end of the selected range.
`setOpen( (isOpen: boolean )): void`	Sets whether the calendar popover is open.
`formatValue( (locale: string, , fieldOptions: FieldOptions )): {start: string, end: string }`	Formats the selected range using the given options.
`open(): void`	Opens the overlay.
`close(): void`	Closes the overlay.
`toggle(): void`	Toggles the overlay's visibility.

RangeValue<DateValue>

RangeValue<TimeValue>

Time
  | CalendarDateTime
  | ZonedDateTime

A Time represents a clock time without any date components.

Properties

Name	Type	Description
`hour`	`number`	The hour, numbered from 0 to 23.
`minute`	`number`	The minute in the hour.
`second`	`number`	The second in the minute.
`millisecond`	`number`	The millisecond in the second.

Methods

Method	Description
`constructor( hour: number, minute: number, second: number, millisecond: number ): void`
`copy(): Time`	Returns a copy of this time.
`add( (duration: TimeDuration )): void`	Returns a new `Time` with the given duration added to it.
`subtract( (duration: TimeDuration )): void`	Returns a new `Time` with the given duration subtracted from it.
`set( (fields: TimeFields )): void`	Returns a new `Time` with the given fields set to the provided values. Other fields will be constrained accordingly.
`cycle( field: TimeField, amount: number, options?: CycleTimeOptions ): void`	Returns a new `Time` with the given field adjusted by a specified amount. When the resulting value reaches the limits of the field, it wraps around.
`toString(): void`	Converts the time to an ISO 8601 formatted string.
`compare( (b: AnyTime )): void`	Compares this time with another. A negative result indicates that this time is before the given one, and a positive time indicates that it is after.

Pick<Intl.DateTimeFormatOptions, 'year'
  | 'month'
  | 'day'
  | 'hour'
  | 'minute'
  | 'second'>

BaseEvent<ReactKeyboardEvent<any>>

SyntheticEvent & {stopPropagation: () => void,
continuePropagation: () => void
}

DateValue extends ZonedDateTime ? ZonedDateTime :
DateValue extends CalendarDateTime ? CalendarDateTime :
DateValue extends CalendarDate ? CalendarDate : never

Name	Type	Description
`type`	`SegmentType`	The type of segment.
`text`	`string`	The formatted text for the segment.
`isPlaceholder`	`boolean`	Whether the value is a placeholder.
`placeholder`	`string`	A placeholder string for the segment.
`isEditable`	`boolean`	Whether the segment is editable.
`value`	`number`	The numeric value for the segment, if applicable.
`minValue`	`number`	The minimum numeric value for the segment, if applicable.
`maxValue`	`number`	The maximum numeric value for the segment, if applicable.

'era'
  | 'year'
  | 'month'
  | 'day'
  | 'hour'
  | 'minute'
  | 'second'
  | 'dayPeriod'
  | 'literal'
  | 'timeZoneName'

Name	Type	Description
`isPlaceholder`	`boolean`	Whether the value is a placeholder.
`isReadOnly`	`boolean`	Whether the segment is read only.
`isInvalid`	`boolean`	Whether the date field is in an invalid state.
`type`	`SegmentType`	The type of segment. Values include `literal`, `year`, `month`, `day`, etc.
`text`	`string`	The formatted text for the segment.
`placeholder`	`string`	A placeholder string for the segment.
`value`	`number`	The numeric value for the segment, if applicable.
`minValue`	`number`	The minimum numeric value for the segment, if applicable.
`maxValue`	`number`	The maximum numeric value for the segment, if applicable.

Name	Type	Description
`isHovered`	`boolean`	Whether the button is currently hovered with a mouse.
`isPressed`	`boolean`	Whether the button is currently in a pressed state.
`isFocused`	`boolean`	Whether the button is focused, either via a mouse or keyboard.
`isFocusVisible`	`boolean`	Whether the button is keyboard focused.
`isDisabled`	`boolean`	Whether the button is disabled.

Name	Type	Description
`type`	`'pressstart' \| 'pressend' \| 'pressup' \| 'press'`	The type of press event being fired.
`pointerType`	`PointerType`	The pointer type that triggered the press event.
`target`	`Element`	The target element of the press event.
`shiftKey`	`boolean`	Whether the shift keyboard modifier was held during the press event.
`ctrlKey`	`boolean`	Whether the ctrl keyboard modifier was held during the press event.
`metaKey`	`boolean`	Whether the meta keyboard modifier was held during the press event.
`altKey`	`boolean`	Whether the alt keyboard modifier was held during the press event.

'mouse'
  | 'pen'
  | 'touch'
  | 'keyboard'
  | 'virtual'

'bottom'
  | 'bottom left'
  | 'bottom right'
  | 'bottom start'
  | 'bottom end'
  | 'top'
  | 'top left'
  | 'top right'
  | 'top start'
  | 'top end'
  | 'left'
  | 'left top'
  | 'left bottom'
  | 'start'
  | 'start top'
  | 'start bottom'
  | 'right'
  | 'right top'
  | 'right bottom'
  | 'end'
  | 'end top'
  | 'end bottom'

Name	Type	Description
`placement`	`PlacementAxis`	The placement of the tooltip relative to the trigger.
`isEntering`	`boolean`	Whether the popover is currently entering. Use this to apply animations.
`isExiting`	`boolean`	Whether the popover is currently exiting. Use this to apply animations.

Axis | 'center'

'top'
  | 'bottom'
  | 'left'
  | 'right'

Represents an amount of time in calendar-specific units, for use when performing arithmetic.

Name	Type	Description
`years`	`number`	The number of years to add or subtract.
`months`	`number`	The number of months to add or subtract.
`weeks`	`number`	The number of weeks to add or subtract.
`days`	`number`	The number of days to add or subtract.

CalendarDate
  | CalendarDateTime
  | ZonedDateTime

Properties

Name	Type	Description
`value`	`CalendarDate`	The currently selected date.
`isDisabled`	`boolean`	Whether the calendar is disabled.
`isReadOnly`	`boolean`	Whether the calendar is in a read only state.
`visibleRange`	`RangeValue<CalendarDate>`	The date range that is currently visible in the calendar.
`timeZone`	`string`	The time zone of the dates currently being displayed.
`validationState`	`ValidationState`	The current validation state of the selected value.
`focusedDate`	`CalendarDate`	The currently focused date.
`isFocused`	`boolean`	Whether focus is currently within the calendar.
`minValue`	`DateValue`	The minimum allowed date that a user may select.
`maxValue`	`DateValue`	The maximum allowed date that a user may select.

Methods

Method	Description
`setValue( (value: CalendarDate )): void`	Sets the currently selected date.
`setFocusedDate( (value: CalendarDate )): void`	Sets the focused date.
`focusNextDay(): void`	Moves focus to the next calendar date.
`focusPreviousDay(): void`	Moves focus to the previous calendar date.
`focusNextRow(): void`	Moves focus to the next row of dates, e.g. the next week.
`focusPreviousRow(): void`	Moves focus to the previous row of dates, e.g. the previous work.
`focusNextPage(): void`	Moves focus to the next page of dates, e.g. the next month if one month is visible.
`focusPreviousPage(): void`	Moves focus to the previous page of dates, e.g. the previous month if one month is visible.
`focusSectionStart(): void`	Moves focus to the start of the current section of dates, e.g. the start of the current month.
`focusSectionEnd(): void`	Moves focus to the end of the current section of dates, e.g. the end of the current month month.
`focusNextSection( (larger?: boolean )): void`	Moves focus to the next section of dates based on what is currently displayed. By default, focus is moved by one of the currently displayed unit. For example, if one or more months are displayed, then focus is moved forward by one month. If the `larger` option is `true`, the focus is moved by the next larger unit than the one displayed. For example, if months are displayed, then focus moves to the next year.
`focusPreviousSection( (larger?: boolean )): void`	Moves focus to the previous section of dates based on what is currently displayed. By default, focus is moved by one of the currently displayed unit. For example, if one or more months are displayed, then focus is moved backward by one month. If the `larger` option is `true`, the focus is moved by the next larger unit than the one displayed. For example, if months are displayed, then focus moves to the previous year.
`selectFocusedDate(): void`	Selects the currently focused date.
`selectDate( (date: CalendarDate )): void`	Selects the given date.
`setFocused( (value: boolean )): void`	Sets whether focus is currently within the calendar.
`isInvalid( (date: CalendarDate )): boolean`	Returns whether the given date is invalid according to the `minValue` and `maxValue` props.
`isSelected( (date: CalendarDate )): boolean`	Returns whether the given date is currently selected.
`isCellFocused( (date: CalendarDate )): boolean`	Returns whether the given date is currently focused.
`isCellDisabled( (date: CalendarDate )): boolean`	Returns whether the given date is disabled according to the `minValue,`maxValue`, and`isDisabled` props.
`isCellUnavailable( (date: CalendarDate )): boolean`	Returns whether the given date is unavailable according to the `isDateUnavailable` prop.
`isPreviousVisibleRangeInvalid(): boolean`	Returns whether the previous visible date range is allowed to be selected according to the `minValue` prop.
`isNextVisibleRangeInvalid(): boolean`	Returns whether the next visible date range is allowed to be selected according to the `maxValue` prop.
`getDatesInWeek( (weekIndex: number, , startDate?: CalendarDate )): Array<CalendarDate \| null>`	Returns an array of dates in the week index counted from the provided start date, or the first visible date if not given. The returned array always has 7 elements, but may include null if the date does not exist according to the calendar system.

DateValue extends ZonedDateTime ? ZonedDateTime :
DateValue extends CalendarDateTime ? CalendarDateTime :
DateValue extends CalendarDate ? CalendarDate : never

Name	Type	Description
`date`	`CalendarDate`	The date that the cell represents.
`formattedDate`	`string`	The day number formatted according to the current locale.
`isHovered`	`boolean`	Whether the cell is currently hovered with a mouse.
`isPressed`	`boolean`	Whether the cell is currently being pressed.
`isSelected`	`boolean`	Whether the cell is selected.
`isSelectionStart`	`boolean`	Whether the cell is the first date in a range selection.
`isSelectionEnd`	`boolean`	Whether the cell is the last date in a range selection.
`isFocused`	`boolean`	Whether the cell is focused.
`isFocusVisible`	`boolean`	Whether the cell is keyboard focused.
`isDisabled`	`boolean`	Whether the cell is disabled, according to the calendar's `minValue`, `maxValue`, and `isDisabled` props. Disabled dates are not focusable, and cannot be selected by the user. They are typically displayed with a dimmed appearance.
`isOutsideVisibleRange`	`boolean`	Whether the cell is outside the visible range of the calendar. For example, dates before the first day of a month in the same week.
`isOutsideMonth`	`boolean`	Whether the cell is outside the current month.
`isUnavailable`	`boolean`	Whether the cell is unavailable, according to the calendar's `isDateUnavailable` prop. Unavailable dates remain focusable, but cannot be selected by the user. They should be displayed with a visual affordance to indicate they are unavailable, such as a different color or a strikethrough. Note that because they are focusable, unavailable dates must meet a 4.5:1 color contrast ratio, as defined by WCAG.
`isInvalid`	`boolean`	Whether the cell is part of an invalid selection.

Parses an ISO 8601 date string, with no time components.

parseDate(
  (value: string
)): CalendarDate

Parses an ISO 8601 date and time string, with no time zone.

parseDateTime(
  (value: string
)): CalendarDateTime

Parses an ISO 8601 date and time string with a time zone extension and optional UTC offset (e.g. "2021-11-07T00:45[America/Los_Angeles]" or "2021-11-07T00:45-07:00[America/Los_Angeles]"). Ambiguous times due to daylight saving time transitions are resolved according to the disambiguation parameter.

parseZonedDateTime(
  (value: string,
  , disambiguation?: Disambiguation
)): ZonedDateTime

'compatible'
  | 'earlier'
  | 'later'
  | 'reject'

Parses an ISO 8601 date and time string with a UTC offset (e.g. "2021-11-07T07:45:00Z" or "2021-11-07T07:45:00-07:00"). The result is converted to the provided time zone.

parseAbsolute(
  (value: string,
  , timeZone: string
)): ZonedDateTime

Parses an ISO 8601 date and time string with a UTC offset (e.g. "2021-11-07T07:45:00Z" or "2021-11-07T07:45:00-07:00"). The result is converted to the user's local time zone.

parseAbsoluteToLocal(
  (value: string
)): ZonedDateTime

useContextProps<T, U, E extends Element>(
  props: T
    &  & SlotProps,
  ref: undefined.ForwardedRef<E>,
  context: undefined.Context<WithRef<SlottedValue<U>
    |  | U, E>>
): [
  T,
  undefined.RefObject<E>
]

Name	Type	Description
`slot`	`string`

T & {ref?: undefined.ForwardedRef<E>
}

Name	Type	Description
`slots`	`Record<string, T>`
`slotCallbackSymbol`	`( (value: T )) => void`

DateRangePicker

Example#

Features#

Anatomy#

Concepts#

Composed components#

Props#

DateRangePicker#

Label#

Group#

DateInput#

DateSegment#

Button#

Popover#

Dialog#

RangeCalendar#

CalendarGrid#

CalendarCell#

Styling#

DateRangePicker#

Label#

Group#

DateInput#

DateSegment#

Button#

Popover#

Dialog#

RangeCalendar#

CalendarGrid#

CalendarCell#

Text#

Reusable wrappers#

Usage#

Value#

Events#

Time zones#

Granularity#

International calendars#

Minimum and maximum values#

Unavailable dates#

Non-contiguous ranges#

Help text#

Placeholder value#

Hide time zone#

Hour cycle#

Advanced customization#

Composition#

Hooks#

Properties

Methods

Properties

Methods

Properties

Methods

Properties

Methods

Properties

Methods

Properties

Methods