DatePicker

The <DatePicker> component is a user interface element that allows users to select a date from a calendar.

The typical practice is to provide a date picker and when you click on calendar button it pops up a calendar below the date field, allowing the user to populate the field with an appropriate date.

Anatomy

The Label defines the purpose of the Date Field, where users can enter a date directly. Tapping the Calendar Button opens a calendar view with a Header for selecting the month and year, and Next/Previous Buttons for easy month navigation.

• Label: Describes which date the user should enter.
• Date field: The field where a date can be typed segment by segment.
• Calendar button: Opens the calendar for picking a date visually.
• Header: The top area of the calendar for selecting month and year.

Appearance

The appearance of a component can be customized using the variant and size props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.

Usage

<DatePicker> is used when you need users to select a date accurately, like for booking events, scheduling appointments, or setting deadlines. It's ideal when date formats might vary, as it standardizes input and reduces mistakes because its visual clarity, format consistency and accuracy. DatePickers are also helpful when users might need guidance on valid date ranges, like selecting only future dates for reservations. Avoid using it for casual date entries where a simple text field would suffice.

Basic Usage (uncontrolled)

This example shows a regular <DatePicker> without any special props.

Min/Max Values

The minValue and maxValue props are used to perform built-in validation. This prevents the user from selecting dates outside the valid range in the calendar .

Controlled

The value and onChange props can be used to control the DatePicker.

Current Selected Date: Day: 29 Month: 10 Year: 2023

Using a Date Object

When using a datepicker, relying on the standard JavaScript Date object for its value can result in timezone inconsistencies and incorrect date display. That's why the datepicker uses a specific DateValue type from @internationalized/date instead. This library handles correct international date manipulation across calendars, time zones, and other localization concerns.

The simplest way to parse a Date for the datepicker is by using parseAbsoluteToLocal. This function converts an absolute date and time into the current user's local time zone. If you're already using a date library like date-fns, you can also utilizing parseDate. Ensure that you only pass the date part to parseDate, excluding the time and timezone information.

Paste Support

The <DatePicker> supports pasting date values from the clipboard. Users can copy dates in common formats and paste them directly into the date picker field. The component automatically parses and validates the pasted content.

Supported date formats:

• ISO format: 2023-12-25
• European format: 25.12.2023 or 25/12/2023
• US format: 12/25/2023 or 12-25-2023

Invalid dates or unrecognized formats are ignored, ensuring data integrity.

Quick select presets

Use the presets prop to offer common dates as a one-click list beside the calendar in the popover, such as "Today" or "Tomorrow" for a due date. Built-in keys ship with localized labels and correct date math, and custom presets take a label plus a date value or a resolver function. Presets that fall outside minValue/maxValue or land on an unavailable date are disabled.

DatePicker accepts the single-date built-ins: today, yesterday and tomorrow. Range keys such as this-week or last-30-days are only available on DateRangePicker and RangeCalendar, where a preset selects a range instead of a single day.

For custom presets, pass value as a function when the date is relative to now (for example "In two weeks"), so it resolves at selection time instead of when the view first rendered. A plain value is right for fixed dates. If you provide several custom presets, give each a unique id: it defaults to the label, so two presets sharing a label would collide.

Combine with a second field

A "From" and "To" pair of <DatePicker>s can each carry their own presets. Feed the other field's value into minValue/maxValue so the range stays valid, and pick presets independently for each end.

Props

DatePicker

Alternative components

• DateRangePicker: Pick a start and end date (a range) through a single field.

• DateField: Allows users to input a date directly.

Related