Skip to content

DateRangePicker

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

Import

import { UNSTABLE_DateRangePicker as DateRangePicker } from "@cfa/react-core";
import { UNSTABLE_DateRangeField as DateRangeField } from "@cfa/react-core";

Live Editor

Examples

Basic Usage

The most common way to use DateRangePicker is with the composite component.

Composable Usage

For more control and customization, use the individual DateRangeField subcomponents.

Controlled Usage

Control the date range value from a parent component.

Date Range Constraints

Set minimum and maximum dates to restrict the selectable range.

Unavailable Dates

Disable specific dates using the isDateUnavailable prop. The example below prevents selection of weekends.

Date Highlighting

Highlight specific dates in the calendar using the isDateHighlighted prop. This example highlights the 1st and 15th of each month.

Non-Contiguous Ranges

Allow users to select non-contiguous date ranges for more flexible selection.

Validation States

The DateRangePicker component supports different validation states.

Date and Time Ranges

Use different granularities for date and time range selection.

Custom Calendar Display

Customize the calendar display with different first day of week and visible duration.

Compact Variant

For smaller spaces, use the compact variant.

Props

Visit the Documentation Site for the full list of props.

NameTypeDefaultDescription
compactbooleanfalseRenders a compact version of the DateRangePicker
descriptionstring-Description for the date range picker
errorMessagestring | ((validation: ValidationResult) => string)-Error message to display when isInvalid is true
isDateHighlighted(date: T) => boolean--
isReadOnlyboolean-Makes the date range picker read-only when true
labelstring-Label for the date range picker
allowsNonContiguousRangesboolean-When combined with `isDateUnavailable`, determines whether non-contiguous ranges, i.e. ranges containing unavailable dates, may be selected.
aria-describedbystring-Identifies the element (or elements) that describes the object.
aria-detailsstring-Identifies the element (or elements) that provide a detailed, extended description for the object.
aria-labelstring-Defines a string value that labels the current element.
aria-labelledbystring-Identifies the element (or elements) that labels the current element.
autoFocusboolean-Whether the element should receive focus on render.
childrenChildrenOrFunction<DateRangePickerRenderProps>-The children of the component. A function may be provided to alter the children based on component state.
classNameClassNameOrFunction<DateRangePickerRenderProps>'react-aria-DateRangePicker'The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state.
defaultOpenboolean-Whether the overlay is open by default (uncontrolled).
defaultValueRangeValue<T>-The default value (uncontrolled).
dirstring--
endNamestring-The name of the end date input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname).
firstDayOfWeek"sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat"-The day that starts the week.
formstring-The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form).
granularityGranularity-Determines the smallest unit that is displayed in the date picker. By default, this is `"day"` for dates, and `"minute"` for times.
hiddenboolean--
hideTimeZonebooleanfalseWhether to hide the time zone abbreviation.
hourCycle12 | 24-Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale.
idstring-The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).
inertboolean--
isDateUnavailable(date: DateValue) => boolean-Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
isDisabledboolean-Whether the input is disabled.
isInvalidboolean-Whether the input value is invalid.
isOpenboolean-Whether the overlay is open by default (controlled).
isRequiredboolean-Whether user input is required on the input before form submission.
langstring--
maxValueDateValue-The maximum allowed date that a user may select.
minValueDateValue-The minimum allowed date that a user may select.
onAnimationEndAnimationEventHandler<HTMLDivElement>--
onAnimationEndCaptureAnimationEventHandler<HTMLDivElement>--
onAnimationIterationAnimationEventHandler<HTMLDivElement>--
onAnimationIterationCaptureAnimationEventHandler<HTMLDivElement>--
onAnimationStartAnimationEventHandler<HTMLDivElement>--
onAnimationStartCaptureAnimationEventHandler<HTMLDivElement>--
onAuxClickMouseEventHandler<HTMLDivElement>--
onAuxClickCaptureMouseEventHandler<HTMLDivElement>--
onBlur(e: FocusEvent<Element, Element>) => void-Handler that is called when the element loses focus.
onChange(value: RangeValue<MappedDateValue<T>>) => void-Handler that is called when the value changes.
onClickMouseEventHandler<HTMLDivElement>--
onClickCaptureMouseEventHandler<HTMLDivElement>--
onContextMenuMouseEventHandler<HTMLDivElement>--
onContextMenuCaptureMouseEventHandler<HTMLDivElement>--
onDoubleClickMouseEventHandler<HTMLDivElement>--
onDoubleClickCaptureMouseEventHandler<HTMLDivElement>--
onFocus(e: FocusEvent<Element, Element>) => void-Handler that is called when the element receives focus.
onFocusChange(isFocused: boolean) => void-Handler that is called when the element's focus status changes.
onGotPointerCapturePointerEventHandler<HTMLDivElement>--
onGotPointerCaptureCapturePointerEventHandler<HTMLDivElement>--
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.
onLostPointerCapturePointerEventHandler<HTMLDivElement>--
onLostPointerCaptureCapturePointerEventHandler<HTMLDivElement>--
onMouseDownMouseEventHandler<HTMLDivElement>--
onMouseDownCaptureMouseEventHandler<HTMLDivElement>--
onMouseEnterMouseEventHandler<HTMLDivElement>--
onMouseLeaveMouseEventHandler<HTMLDivElement>--
onMouseMoveMouseEventHandler<HTMLDivElement>--
onMouseMoveCaptureMouseEventHandler<HTMLDivElement>--
onMouseOutMouseEventHandler<HTMLDivElement>--
onMouseOutCaptureMouseEventHandler<HTMLDivElement>--
onMouseOverMouseEventHandler<HTMLDivElement>--
onMouseOverCaptureMouseEventHandler<HTMLDivElement>--
onMouseUpMouseEventHandler<HTMLDivElement>--
onMouseUpCaptureMouseEventHandler<HTMLDivElement>--
onOpenChange(isOpen: boolean) => void-Handler that is called when the overlay's open state changes.
onPointerCancelPointerEventHandler<HTMLDivElement>--
onPointerCancelCapturePointerEventHandler<HTMLDivElement>--
onPointerDownPointerEventHandler<HTMLDivElement>--
onPointerDownCapturePointerEventHandler<HTMLDivElement>--
onPointerEnterPointerEventHandler<HTMLDivElement>--
onPointerLeavePointerEventHandler<HTMLDivElement>--
onPointerMovePointerEventHandler<HTMLDivElement>--
onPointerMoveCapturePointerEventHandler<HTMLDivElement>--
onPointerOutPointerEventHandler<HTMLDivElement>--
onPointerOutCapturePointerEventHandler<HTMLDivElement>--
onPointerOverPointerEventHandler<HTMLDivElement>--
onPointerOverCapturePointerEventHandler<HTMLDivElement>--
onPointerUpPointerEventHandler<HTMLDivElement>--
onPointerUpCapturePointerEventHandler<HTMLDivElement>--
onScrollUIEventHandler<HTMLDivElement>--
onScrollCaptureUIEventHandler<HTMLDivElement>--
onTouchCancelTouchEventHandler<HTMLDivElement>--
onTouchCancelCaptureTouchEventHandler<HTMLDivElement>--
onTouchEndTouchEventHandler<HTMLDivElement>--
onTouchEndCaptureTouchEventHandler<HTMLDivElement>--
onTouchMoveTouchEventHandler<HTMLDivElement>--
onTouchMoveCaptureTouchEventHandler<HTMLDivElement>--
onTouchStartTouchEventHandler<HTMLDivElement>--
onTouchStartCaptureTouchEventHandler<HTMLDivElement>--
onTransitionCancelTransitionEventHandler<HTMLDivElement>--
onTransitionCancelCaptureTransitionEventHandler<HTMLDivElement>--
onTransitionEndTransitionEventHandler<HTMLDivElement>--
onTransitionEndCaptureTransitionEventHandler<HTMLDivElement>--
onTransitionRunTransitionEventHandler<HTMLDivElement>--
onTransitionRunCaptureTransitionEventHandler<HTMLDivElement>--
onTransitionStartTransitionEventHandler<HTMLDivElement>--
onTransitionStartCaptureTransitionEventHandler<HTMLDivElement>--
onWheelWheelEventHandler<HTMLDivElement>--
onWheelCaptureWheelEventHandler<HTMLDivElement>--
pageBehaviorPageBehaviorvisibleControls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.
placeholderValueDateValue-A placeholder date that influences the format of the placeholder shown when no value is selected. Defaults to today's date at midnight.
renderDOMRenderFunction<"div", DateRangePickerRenderProps>-Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: * You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). * Only a single root DOM element can be rendered (no fragments). * You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
shouldCloseOnSelectboolean | (() => boolean)trueDetermines whether the date picker popover should close automatically when a date is selected.
shouldForceLeadingZerosboolean-Whether to always show leading zeros in the month, day, and hour fields. By default, this is determined by the user's locale.
slotstring-A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.
startNamestring-The name of the start date input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname).
styleStyleOrFunction<DateRangePickerRenderProps>-The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state.
translate"yes" | "no"--
validate(value: RangeValue<MappedDateValue<T>>) => true | ValidationError-A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead.
validationBehavior"native" | "aria"'native'Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
valueRangeValue<T>-The current value (controlled).
visibleDurationDateDuration{months: 1}The amount of days that will be displayed at once. This affects how pagination works.