DatePicker
Popover date and date-range picker controls with quick month and year navigation.
Quick Preview
Usage
<DatePicker value={date} onChange={setDate} />
<DateRangePicker value={range} onChange={setRange} />Examples
Default DatePicker
Use this as the starting point for DatePicker. The calendar caption renders month and year dropdowns by default, so users can jump to any month without paging. Keep product data, routing, fetching, and authorization logic in the consuming app.
Date range
DateRangePicker shares the same trigger and footer, but selects a { from, to } range.
Disabled dates
Pass a react-day-picker matcher to disabledDates to block selection — for example, all dates before today.
Trigger sizes
Use size to match surrounding form controls. It changes only the trigger; the calendar panel keeps its standard dimensions.
<DatePicker size="sm" />
<DatePicker size="md" />
<DatePicker size="lg" />
<DatePicker size="xl" />Props
Both DatePicker and DateRangePicker accept the shared props below; they differ only in value/onChange types.
| Prop/API | Type | Default | Description |
|---|---|---|---|
value | `Date | undefined(DatePicker) /DateRange | undefined` (DateRangePicker) |
onChange | (next) => void | - | Called with the applied date/range, or undefined on clear. |
captionLayout | `"label" | "dropdown" | "dropdown-months" |
startMonth | Date | 100 years ago | Earliest navigable month (also bounds the year dropdown). |
endMonth | Date | 10 years ahead | Latest navigable month (also bounds the year dropdown). |
disabledDates | `Matcher | Matcher[]` | - |
disabled | boolean | false | Disables the trigger. |
size | `"sm" | "md" | "lg" |
placeholder | string | "Select date" | Trigger placeholder copy. |
side / align | base-ui positioner props | "bottom" / "center" | Preferred placement for the panel. Preferences only — the panel moves to whichever side it fits on, the perpendicular ones included. |
sideOffset / alignOffset | number | 6 / 0 | Distance from the trigger. |
collisionAvoidance | base-ui CollisionAvoidance | popover default | How the panel reacts to running out of room. Pass { side: "none" } to hold the preferred side even when it overflows. |
className | string | - | Local layout or spacing overrides. |
| native/root props | React component props | - | Passed through to the underlying root or primitive. |
Accessibility
- Provide visible labels or accessible names for interactive controls.
- Month and year dropdowns are labelled searchable comboboxes; the calendar grid keeps react-day-picker keyboard navigation.
- Preserve the component-provided focus, keyboard, disabled, and invalid-state behavior.
- Do not communicate state with color alone; include text, icons, or helper copy.