DatePicker
A date picker allows users to select a single date from a calendar.
Usage
Value
A DatePicker displays a placeholder by default. An initial, uncontrolled value can be provided to the DatePicker using the defaultValue prop. Alternatively, a controlled value can be provided using the value prop.
Date values are provided using objects in the @internationalized/date package. This library handles correct international date manipulation across calendars, time zones, and other localization concerns. DatePicker 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 aZonedDateTime.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.
Controlled
A DatePicker can handle value state in controlled mode.
Validation
Invalid
A DatePicker 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
DatePicker 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. When an unavailable date is entered into the date field, it is marked as invalid. The isDateUnavailable prop accepts a callback that is called to evaluate whether each visible date is unavailable.
This example includes multiple unavailable date ranges, e.g. dates when no appointments are available. In addition, all weekends are unavailable. The minValue prop is also used to prevent selecting dates before today.
Custom Validation
The validate function can be used to perform custom validation logic. It receives the current date value, 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 is a weekday and not a weekend according to the current locale.
Description
The description prop can be used to provide additional context about the DatePicker.
Props
If true, the DatePicker will take all available width.
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.
Describes the type of autocomplete functionality the input should provide if any. See MDN.
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.
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.
Whether the element should receive focus on render.
Whether the overlay is open by default (controlled).
Whether the overlay is open by default (uncontrolled).
The current value (controlled).
The default value (uncontrolled).
The name of the input element, used when submitting an HTML form. See MDN.
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.