DatePicker
A date picker combines a DateField and a Calendar popover to allow users to enter or select a date and time value.
DatePicker 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.
Import
import { DatePicker, DateField } from "@cfa/react-core";import { CalendarDate, CalendarDateTime } from "@cfa/react-core/dates";Live Editor
Guidelines
When to use
- DatePicker is for a single date, when calendar context improves accuracy or people may not know the exact date.
Do
- Prefer the typeable field when people already know the date. The calendar popover supplements entry.
- Pair with TimeInput when time-of-day precision is required.
- Disable or constrain dates that fall outside allowed ranges or business rules, including minimums, maximums, and specific blocked dates.
- Show a clear inline error when the typed date violates a constraint.
- Validate when people leave the field or submit the form, not on every keystroke.
Avoid
- Using DatePicker for date ranges. Use DateRangePicker.
- Using DatePicker for time of day. Use TimeInput.
- Using DatePicker when the choice is one of a few fixed dates. Use Select or RadioGroup.
- Relying on the calendar grid alone.
- Silently snapping a typed date to a valid value.
Examples
Basic Usage
The most common way to use DatePicker is with the composite component.
Composable Usage
For more control, use the individual subcomponents.
Controlled Usage
Control the date value from a parent component.
Date Ranges
Set minimum and maximum dates to restrict selection.
Disabled Dates
Disable specific dates using the isDateUnavailable prop. The example below disables the weekends.
Date Highlighting
Highlight specific dates in the calendar using the isDateHighlighted prop. This example highlights the 1st and 15th of each month.
Validation States
The DatePicker component supports different validation states.
Date and Time
Use different granularities for date and time selection.
Calendar Customizations
Customize the calendar display by changing the first day of week and the number of visible months.
Sizes
Use the size prop (sm, md, or lg) to control field height, padding, and segment typography. Default is md (40px).