Date Picker
Pick one date from a calendar popover.
- Dates people know by heart (birthdays): use Input with three fields or type="date".
- Date ranges: use Calendar mode="range" (range picker in Wave 3).
Install
Terminal
pnpm dlx shadcn@latest add @acme/date-pickerOr import from the package: import { DatePicker } from '@acme/react'
Examples
Picker basic
Invoice due date
Start date
date-picker-basic.tsx
'use client'
import { DatePicker } from '@/components/ui/date-picker'
// A fixed date keeps the example (and its screenshots) stable.
const today = new Date(2026, 9, 3)
export default function DatePickerBasic() {
return (
<div className="flex w-full max-w-xs flex-col gap-6">
<DatePicker label="Invoice due date" name="dueDate" defaultValue={new Date(2026, 9, 31)} />
<DatePicker
label="Start date"
placeholder="Choose a start date"
calendarProps={{ disabled: { before: today }, defaultMonth: today }}
/>
</div>
)
}Props
| Prop | Type | Default | Description |
|---|---|---|---|
| label (required) | ReactNode | — | Visible label; names the trigger. |
| value / defaultValue / onValueChange | Date | — | Selected date. |
| name | string | — | Submits YYYY-MM-DD with forms. |
| placeholder | string | 'Pick a date' | Shown when empty. |
| locale | string | — | BCP 47 locale for the trigger text. |
| calendarProps | CalendarProps | — | Passed to Calendar, e.g. disabled dates. |
Accessibility
| Key | Action |
|---|---|
| Enter / Space | Opens; focus moves to the selected (or today's) date |
| Arrow keys / Page Up / Down | Navigate days and months |
| Enter | Selects and closes |
| Escape | Closes and returns focus |
- Role
- button + dialog with grid
- You provide
- label (enforced by TypeScript).
- Built in
- The trigger reads as "<label> <date>" so the value is announced.
- WCAG 2.2 criteria
- 1.3.1, 2.1.1, 4.1.2
Don’t
- Force the calendar for dates far in the past.
Tokens
- color.input
- color.popover
- color.primary
- elevation.2
- z.popover