DateRangePicker
A date range picker combines two DateFields and a RangeCalendar popover to allow users to enter or select a date range.
DateRangePicker uses typed objects from @internationalized/date instead of native JavaScript Date. Import date utilities from @cfa/react-core/dates and components from @cfa/react-core. See the Dates and Times guide for how to create values and convert to and from Date.
For an inline calendar without fields, use RangeCalendar.
Import
import { DateRangePicker, DateRangeField } from "@cfa/react-core";import { CalendarDate, CalendarDateTime } from "@cfa/react-core/dates";Live Editor
Guidelines
When to use
- DateRangePicker is for a start and end date people pick as one value, shown as a span in a calendar.
Do
- Disable invalid days, such as days before the start date, days past a maximum span, and blackout days. Update disabled days dynamically when constraints depend on the start date.
- Show a clear inline error when the typed range violates a constraint.
Avoid
- Using DateRangePicker when only one date matters. Use DatePicker.
- Using DateRangePicker when the two dates are unrelated. Use two DatePickers.
- Using DateRangePicker when the unit is time of day. Use TimeInput.
- Using DateRangePicker when the range is one of a few preset choices with no custom picking. Use Select or RadioGroup.
- Using DateRangePicker when the range is really a duration. Use NumberInput and a unit selector.
- Silently snapping a typed range to a valid value.
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.
Sizes
Use the size prop (sm, md, or lg) to control field height, padding, and segment typography. Default is md (40px).