Search for a command to run...
An outline button that opens a Calendar in a popover. `DatePicker` for a single date, `DateRangePicker` for a from/to range. Defaults to dropdown month + year navigation so users can jump anywhere without arrow-spamming.
The picker is controlled-only — hold the date in useState (or a form library) and pass it via value / onValueChange. The popover stays open until the user clicks outside (or presses Escape) so they can confirm the selection visually; set autoClose to dismiss immediately on pick.
DatePicker| Prop | Type | Default | Description |
|---|---|---|---|
value | Date | undefined | — | Currently selected date. |
onValueChange | (date: Date | undefined) => void | — | Fires when the user picks or clears the date. |
placeholder | string | "Pick a date" | Trigger text when no date is selected. |
formatString | string | "PPP" | date-fns/format string applied to the trigger when a date is selected (e.g. "PPP" → "May 19th, 2026"). |
disabled | (date: Date) => boolean | — | Predicate that disables matching dates from selection. |
startMonth | Date | 100 years ago | Earliest navigable month. Drives the year dropdown's lower bound. |
endMonth | Date | 5 years from now | Latest navigable month. Drives the year dropdown's upper bound. |
captionLayout | "dropdown" | "dropdown-months" | "dropdown-years" | "label" | "dropdown" | Caption navigation. "dropdown" shows month + year selects; "label" is the static text-only header. |
autoClose | boolean | false | Close the popover the moment a date is picked. Default false — dismiss happens on outside click so users can see the chosen date in context. Opt in for tight forms. |
defaultMonth | Date | value or today | Calendar's initial month when no value is selected. |
className | string | — | Classes applied to the trigger Button. |
DateRangePickerSame props as DatePicker, with these differences:
| Prop | Type | Default | Description |
|---|---|---|---|
value | DateRange | undefined | — | Currently selected range ({ from, to? } from react-day-picker). |
onValueChange | (range: DateRange | undefined) => void | — | Fires when the range changes. |
placeholder | string | "Pick a date range" | Trigger text when no range is selected. |
formatString | string | "LLL dd, y" | date-fns/format string applied to each endpoint (e.g. "May 19, 2026"). |
numberOfMonths | number | 2 | Months shown side-by-side inside the popover. |
autoClose | boolean | false | Close the popover once both from and to are set. Default false — dismiss happens on outside click so users can confirm the band visually. Opt in for tight forms. |
Use DatePicker / DateRangePicker for plain "pick a date" form fields. Reach for Calendar
directly only when you need custom chrome around the grid (presets, an Apply footer, embedded in
a sheet).
Pass a disabled predicate to block out invalid dates. Combine with startMonth/endMonth
when there's a hard cliff (e.g. don't let users navigate before account creation).
Build a custom popover + calendar combo. If DatePicker doesn't fit, compose Calendar inside
a Popover you own — the open/close ergonomics are the only thing this component contributes.
Force captionLayout="label" to "tidy up" the caption. Static labels make users arrow-spam to
reach distant months — the dropdown caption is the default for a reason.