Date picker
A date field and calendar popover on react-aria-components. Adapted from BoardUI (MIT).
Dates go in and out as ISO strings such as 2026-03-12. A pick is staged until Apply. The Calendar it also exports is the bare month, which commits on every pick: use it where the picker already sits in a menu.
With a label
import { DatePicker } from "@/components/ui/date-picker"
import { Label } from "@/components/ui/label"
export default function DatePickerWithALabel() {
return (
<div className="grid w-48 gap-2">
<Label htmlFor="date-picker-due">Due date</Label>
<DatePicker id="date-picker-due" defaultValue="2026-03-12" className="w-full" />
</div>
)
}
Empty
import { DatePicker } from "@/components/ui/date-picker"
import { Label } from "@/components/ui/label"
export default function DatePickerEmpty() {
return (
<div className="grid w-48 gap-2">
<Label htmlFor="date-picker-start">Start date</Label>
<DatePicker id="date-picker-start" placeholder="No start date" className="w-full" />
</div>
)
}
Earliest and latest
Within the sprint, 9 to 20 March 2026.
import { DatePicker } from "@/components/ui/date-picker"
import { FieldDescription } from "@/components/ui/field"
import { Label } from "@/components/ui/label"
export default function DatePickerEarliestAndLatest() {
return (
<div className="grid w-56 gap-2">
<Label htmlFor="date-picker-review">Review date</Label>
<DatePicker
id="date-picker-review"
defaultValue="2026-03-12"
min="2026-03-09"
max="2026-03-20"
aria-describedby="date-picker-review-description"
className="w-full"
/>
<FieldDescription id="date-picker-review-description">Within the sprint, 9 to 20 March 2026.</FieldDescription>
</div>
)
}
Required in a form
"use client"
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { DatePicker } from "@/components/ui/date-picker"
import { Label } from "@/components/ui/label"
export default function DatePickerRequiredInAForm() {
const [sent, setSent] = useState<string | null>(null)
return (
<form
className="grid w-56 gap-3"
onSubmit={(event) => {
event.preventDefault()
setSent(String(new FormData(event.currentTarget).get("issued")))
}}
>
<div className="grid gap-2">
<Label htmlFor="date-picker-issued">Issue date</Label>
<DatePicker id="date-picker-issued" name="issued" required className="w-full" />
</div>
<Button type="submit">Create invoice</Button>
<p role="status" className="min-h-5 text-xs text-muted-foreground">
{sent ? `Submitted issued=${sent}` : null}
</p>
</form>
)
}
Ghost
- Due
- Paid
import { DatePicker } from "@/components/ui/date-picker"
export default function DatePickerGhost() {
return (
<dl className="grid w-full max-w-xs grid-cols-[6rem_1fr] items-center gap-x-2 gap-y-1 text-base">
<dt className="text-muted-foreground">Due</dt>
<dd>
<DatePicker variant="ghost" aria-label="Due date" defaultValue="2026-03-12" className="w-full" />
</dd>
<dt className="text-muted-foreground">Paid</dt>
<dd>
<DatePicker variant="ghost" aria-label="Paid date" placeholder="Not paid" className="w-full" />
</dd>
</dl>
)
}
Disabled
import { DatePicker } from "@/components/ui/date-picker"
import { Label } from "@/components/ui/label"
export default function DatePickerDisabled() {
return (
<div className="group grid w-48 gap-2" data-disabled="true">
<Label htmlFor="date-picker-closed">Closed on</Label>
<DatePicker id="date-picker-closed" defaultValue="2026-02-27" disabled className="w-full" />
</div>
)
}
Invalid
Choose a date on or after the issue date, 9 Mar 2026.
import { DatePicker } from "@/components/ui/date-picker"
import { Field, FieldError, FieldLabel } from "@/components/ui/field"
export default function DatePickerInvalid() {
return (
<Field data-invalid="true" className="w-64">
<FieldLabel htmlFor="date-picker-payment">Payment date</FieldLabel>
<DatePicker
id="date-picker-payment"
defaultValue="2026-03-01"
aria-invalid
aria-describedby="date-picker-payment-error"
/>
<FieldError id="date-picker-payment-error">Choose a date on or after the issue date, 9 Mar 2026.</FieldError>
</Field>
)
}
Calendar alone
March 2026
| Mo | Tu | We | Th | Fr | Sa | Su |
|---|---|---|---|---|---|---|
1 | ||||||
2 | 3 | 4 | 5 | 6 | 7 | 8 |
9 | 10 | 11 | 12 | 13 | 14 | 15 |
16 | 17 | 18 | 19 | 20 | 21 | 22 |
23 | 24 | 25 | 26 | 27 | 28 | 29 |
30 | 31 |
Value: 2026-03-12
"use client"
import { useState } from "react"
import { Calendar } from "@/components/ui/date-picker"
export default function DatePickerCalendarAlone() {
const [due, setDue] = useState("2026-03-12")
return (
<div className="grid justify-items-center gap-2">
<Calendar aria-label="Due date" value={due} onValueChange={setDue} />
<p className="text-xs text-muted-foreground tabular-nums">Value: {due}</p>
</div>
)
}
Installation
npx shadcn@latest add @khaeli/date-pickerbunx --bun shadcn@latest add @khaeli/date-pickerInstall @khaeli/foundation first: this item's styling lives in its tokens and [data-slot] rules.
Installs with
- Registry items
- npm packages
- @internationalized/date ^3.12.1
- @keyline-icons/react ^2.2.0
- motion ^12.23.12
- react-aria-components ^1.17.0
Keyboard
EnterSpace- On the field, open the calendar: focus lands on the chosen day, or on today. On a day, stage it: the field keeps its date until Apply.
ArrowLeftArrowRightArrowUpArrowDown- Move focus by a day and by a week. Days outside
minandmaxcannot be reached. HomeEnd- Move focus to the first and to the last day of the month.
PageUpPageDown- Move focus to the same day in the month before and the month after.
Shift + PageUpShift + PageDown- Move focus to the same day in the year before and the year after.
Tab- Moves from the days to the date box, then to Clear, Cancel and Apply. Shift + Tab moves back to the month buttons.
Escape- Closes the calendar and drops a staged day. Focus returns to the field.
Accessible name
- The field is a button with
role="combobox": its date is read as its value. Passidand point a @khaeli/label at it withhtmlFor, or passaria-label. aria-labelalso names the popover's dialog and its calendar ("Due date, March 2026"). Named by a label alone, the dialog is called "Choose date" and the calendar "Date".- Each day is named in full, such as "Thursday, 12 March 2026 selected". The month buttons are Previous and Next, and the date box is "Date, DD/MM/YYYY": type a date there and press Enter to move the calendar to it.
aria-invalidandaria-describedbygo to the field, so an error message is read as its description.- With
name, the ISO date is submitted with the form. Withrequired, the browser's own validation stops an empty submit.
Registry JSON
The item as the shadcn CLI reads it, with every file it ships: https://ui.khaeli.com/r/date-picker.json