Date Picker

A date field that understands typed dates like next fri.

Source
$npx @dinachi/cli@latest add date-picker

No date yet

presentation
noPast
weekdaysOnly
dropdown
disabled

Usage

import { useState } from "react"
import { DatePicker } from "@/components/ui/date-picker"

export function DueDate() {
  const [due, setDue] = useState<Date | null>(null)
  return <DatePicker aria-label="Due date" value={due} onValueChange={setDue} min={new Date()} />
}

Examples

No date yet

Due from today on.
import { useState } from 'react';
import { DatePicker } from '@/components/ui/date-picker';

export function Example() {
  const [due, setDue] = useState<Date | null>(null);
  return <DatePicker aria-label="Due date" label="Due date" value={due} onValueChange={setDue} min={new Date()} />;
}

Notes

Server rendering

Pass today when the page renders on a server, so the server and the browser agree on which day it is.

Typing first

The line under the field shows the day it reads before anything commits, and how far away it is. Text that isn't a date, or a day that can't be picked, says why there and marks the field invalid; it is never thrown away. So does a value set from outside that can't be picked. A two-digit year lands inside min and max when it can, so 75 in a birth date field is 1975. Esc puts back the last committed day.

On phones

Below 768px the calendar opens in a drawer with its own field, preset chips and a confirm button. Nothing commits until that button is pressed, so swiping the drawer away leaves the value as it was.

API

value
agent
Date | null
Controlled value, a day at local midnight.
defaultValueDate | null
Starting value when uncontrolled.
onValueChange
agent
(value, details) => void
Runs when a day commits: on Enter, on leaving the field, on a calendar pick, or on the drawer's button. details.cancel() refuses it.
min
agent
Date
The earliest day. Typing an earlier one shows why it can't be used.
max
agent
Date
The latest day.
isDateDisabled
agent
(date: Date) => boolean
Blocks single days, typed or picked.
parseDate(text, { today, min, max }) => Date | null
Replaces the parser, for other languages or formats.
captionLayout"label" | "dropdown" = "label"
dropdown gives the calendar month and year selects, for days years away such as a birth date.
formatDate(date: Date) => string = Fri, 21 Nov 2026
How a committed day reads in the field.
presets{ label: string; value: Date }[]
Chips in the phone drawer. Defaults to today, tomorrow, Saturday, next Monday and in a week. Blocked ones are dropped.
presentation"auto" | "popover" | "drawer" = "auto"
A popover from 768px up and a drawer below, unless one is named.
labelstring = "Choose a date"
Names the calendar button and popover, and titles the drawer.
confirmLabelstring = "Set date"
The drawer's button.
placeholderstring = "next fri or 21 nov"
Shows what can be typed.
namestring
Submits the day with a form as YYYY-MM-DD.
requiredboolean = false
Validated on the field itself, so the browser points at it.
disabled
agent
boolean = false
Blocks people and agents.
weekNumbers, locale, weekStartsOn, dir, todayAs Calendar
Passed to the calendar. locale also sets how 3/12 is read.

Agent

Inside an AgentProvider, it appears in agent.snapshot() as date.

Reads

label

The field's aria-label.

value

YYYY-MM-DD, or absent when empty.

invalid, errors

Set while the field holds text that doesn't read, with the message the person sees.

disabled

True when the picker is blocked.

Actions

setValue("2026-12-24")

Commits the day. Phrases work too: next fri, in 2 weeks, 21 nov.

clear()

Empties the value.

An agent's change runs through onValueChange like anyone's. isAgentChange(details) is true for it; details.cancel() refuses it. Days the field would refuse are refused with the same words.

await agent.act({
  steps: [{ ref: "Due date", action: "setValue", args: ["next fri"] }],
})

Accessibility

  • The line under the field is a live region tied to the field by aria-describedby, so the reading is announced as you type.
  • An unreadable entry sets aria-invalid and the field's validation message.
  • The calendar button's name includes the committed day.
  • Picking a day returns focus to the field.