DateRangePicker
A date range picker allows users to select a range of dates from a calendar.
Usage
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 theparseZonedDateTime,parseAbsolute, orparseAbsoluteToLocalfunctions. Use this type to represent an exact moment in time at a particular location on Earth.
Controlled
A DateRangePicker can handle value state in controlled mode.
Validation
Invalid
A DateRangePicker can be marked as invalid.
Min and Max
The minValue and maxValue props can be used to limit the range of dates that a user can select.
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 validate 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 validate prop is used to mark selected date ranges with unavailable dates in the middle as invalid.
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.
Custom Validation
The validate function can be used to perform custom validation logic. It receives the current date range, and should return a string or array of strings representing one or more error messages if the value is invalid.
This example validates that the selected date range is a maximum of 1 week in duration.
Description
The description prop can be used to provide additional context about the DateRangePicker.
Props
If true, the DateRangePicker will take all available width.
A ref for the HTML input element.
A ref for the HTML input element.
The props for the InputGroup.
The maximum number of months to display at once in the calendar popover, if screen space permits.
Whether the calendar should always display 6 weeks. This ensures that the height of the popover does not change between months, causing layout shifts.
The props for the popover.
The props for the calendar.
The element to associate the input with. The value of this attribute must be the id of a in the same document.
See MDN.
The inline style for the element. A function may be provided to compute the style based on component state.
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.
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.
Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.
The day that starts the week.
The minimum allowed date that a user may select.
The maximum allowed date that a user may select.
Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
A placeholder date that influences the format of the placeholder shown when no value is selected. Defaults to today's date at midnight.
Whether to hide the time zone abbreviation.
Whether to always show leading zeros in the month, day, and hour fields. By default, this is determined by the user's locale.
Whether the input is disabled.
Whether the input can be selected but not changed by the user.
Whether user input is required on the input before form submission.
Whether the input value is invalid.
Whether the element should receive focus on render.
Whether the overlay is open by default (controlled).
Whether the overlay is open by default (uncontrolled).
When combined with isDateUnavailable, determines whether non-contiguous ranges,
i.e. ranges containing unavailable dates, may be selected.
The name of the start date input element, used when submitting an HTML form. See MDN.
The name of the end date input element, used when submitting an HTML form. See MDN.
The current value (controlled).
The default value (uncontrolled).
Determines whether the date picker popover should close automatically when a date is selected.
The CSS className for the element. A function may be provided to compute the class based on component state.
A function to create a new Calendar
object for a given calendar identifier. If not provided, the createCalendar function
from @internationalized/date will be used.
The helper message of the field.
The error message of the field.
The label of the field.
Whether the required state should be shown as an asterisk or a label, which would display (Optional) on all non required field labels.
A Field can vary in size.
A ContextualHelp element to place next to the label.