Nothing picked
modelayoutcaptionLayoutweekNumbersdisabledimport { useState } from "react"
import { Calendar } from "@/components/ui/calendar"
export function DatePanel() {
const [value, setValue] = useState<Date | null>(null)
return (
<Calendar
aria-label="Due date"
value={value}
onValueChange={setValue}
/>
)
}Usage
import { useState } from "react"
import { Calendar } from "@/components/ui/calendar"
export function DueDate() {
const [day, setDay] = useState<Date | null>(null)
return <Calendar aria-label="Due date" value={day} onValueChange={setDay} />
}Examples
No day picked
import { useState } from 'react';
import { Calendar, toISODate } from '@/components/ui/calendar';
export function Example() {
const [day, setDay] = useState<Date | null>(null);
return (
<div className="grid justify-items-center gap-3">
<Calendar aria-label="Due date" value={day} onValueChange={setDay} className="rounded-lg border" />
<p className="text-sm text-muted-foreground">{day ? toISODate(day) : "No day picked"}</p>
</div>
);
}| Mo | Tu | We | Th | Fr | Sa | Su |
|---|---|---|---|---|---|---|
| Mo | Tu | We | Th | Fr | Sa | Su |
|---|---|---|---|---|---|---|
import { useState } from 'react';
import { Calendar, type DateRange } from '@/components/ui/calendar';
export function Example() {
const [range, setRange] = useState<DateRange>({ from: null, to: null });
return (
<Calendar
mode="range"
layout="paged"
numberOfMonths={2}
aria-label="Stay"
value={range}
onValueChange={setRange}
min={new Date()}
className="rounded-lg border p-3"
/>
);
}| 18 | |||||||
|---|---|---|---|---|---|---|---|
| 19 | |||||||
| 20 | |||||||
| 21 | |||||||
| 22 |
| 23 | |||||||
|---|---|---|---|---|---|---|---|
| 24 | |||||||
| 25 | |||||||
| 26 | |||||||
| 27 |
| 27 | |||||||
|---|---|---|---|---|---|---|---|
| 28 | |||||||
| 29 | |||||||
| 30 | |||||||
| 31 |
| 31 | |||||||
|---|---|---|---|---|---|---|---|
| 32 | |||||||
| 33 | |||||||
| 34 | |||||||
| 35 | |||||||
| 36 |
| 36 | |||||||
|---|---|---|---|---|---|---|---|
| 37 | |||||||
| 38 | |||||||
| 39 | |||||||
| 40 |
| 40 | |||||||
|---|---|---|---|---|---|---|---|
| 41 | |||||||
| 42 | |||||||
| 43 | |||||||
| 44 |
| 44 | |||||||
|---|---|---|---|---|---|---|---|
| 45 | |||||||
| 46 | |||||||
| 47 | |||||||
| 48 | |||||||
| 49 |
| 49 | |||||||
|---|---|---|---|---|---|---|---|
| 50 | |||||||
| 51 | |||||||
| 52 | |||||||
| 53 |
| 53 | |||||||
|---|---|---|---|---|---|---|---|
| 01 | |||||||
| 02 | |||||||
| 03 | |||||||
| 04 |
| 05 | |||||||
|---|---|---|---|---|---|---|---|
| 06 | |||||||
| 07 | |||||||
| 08 |
| 09 | |||||||
|---|---|---|---|---|---|---|---|
| 10 | |||||||
| 11 | |||||||
| 12 | |||||||
| 13 |
| 13 | |||||||
|---|---|---|---|---|---|---|---|
| 14 | |||||||
| 15 | |||||||
| 16 | |||||||
| 17 |
| 17 | |||||||
|---|---|---|---|---|---|---|---|
| 18 | |||||||
| 19 | |||||||
| 20 | |||||||
| 21 | |||||||
| 22 |
import { Calendar } from '@/components/ui/calendar';
export function Example() {
return (
<Calendar
mode="multiple"
aria-label="Rota days"
weekNumbers
isDateDisabled={(d) => d.getDay() === 0 || d.getDay() === 6}
className="rounded-lg border"
/>
);
}Notes
What a day is
A day is a Date at local midnight, so it names the same calendar day wherever it is read. Nothing converts time zones. Forms receive YYYY-MM-DD, and toISODate gives you the same string.
Scrolling months
The scroll layout renders a window of months around the value and adds more as you near either end, stopping at min and max. The Today button appears once today has scrolled out of view. Use layout="paged" to embed the calendar where a scroll area doesn't fit.
Ranges and blocked days
A range can't run across a day that can't be picked. The preview stops short of one, and pressing past it starts a new range with the reason range-blocked, which you can cancel or explain. A value set from outside that breaks the rule marks the calendar data-invalid and paints the blocked days inside the band.
Date helpers
calendar.tsx also exports the helpers the date components share: parseDate reads what people type (today, next fri, in 2 weeks, 21 nov, 3/12, read in the order the page's language writes dates; a two-digit year lands inside min and max, else up to twenty years ahead), plus toISODate, fromISODate, isSameDay, addDays, daysBetween and isoWeek.
API
mode.details.cancel() refuses the change.dropdown turns each month heading into month and year selects, for dates years away like a birthday. Years run from min to max, else a century back and twenty years ahead.YYYY-MM-DD or YYYY-MM-DD/YYYY-MM-DD.Agent
Inside an AgentProvider, it appears in agent.snapshot() as date.
Reads
labelThe calendar's aria-label.
valueYYYY-MM-DD, a list of them in multiple mode, or [from, to] for a range.
multipleTrue in multiple and range modes, where the value is a list.
disabledTrue when the calendar is blocked.
invalidTrue when the value names a day that can't be picked, or a range runs across one.
Actions
setValue("2026-12-24")Picks the day and scrolls to it. Phrases work too: next fri, in 2 weeks, 21 nov.
setValue(["2026-12-21", "2026-12-24"])Sets a range, or the days in multiple mode. Refuses a range that ends before it starts.
clear()Empties the value.
An agent's change runs through onValueChange like anyone's. isAgentChange(details) is true for it; details.cancel() refuses it and the agent is told the app refused. Days outside min and max, days isDateDisabled blocks, and text that isn't a date are refused with the reason.
await agent.act({
steps: [{ ref: "Due date", action: "setValue", args: ["next fri"] }],
})Accessibility
- Each month is a grid. Every day is a button whose name is the full date.
- Picked days, and every day inside a picked range, carry aria-selected. A previewed range is drawn but not announced.
- Only one day is in the tab order: the picked day, else today. Arrows move from there.
- Today is marked with a dot as well as its name, not colour alone.
- The range band is a primary tint with a 3:1 edge against the surface, in light and dark.
- The paged arrows are plain buttons, Previous month and Next month, not a navigation landmark.
- If scrolling drops the month holding focus, focus moves to the nearest day still shown.
- Reduced motion turns off the smooth scroll to today.
Keyboard
min and max and stepping off days that can't be pickedmin and max and stepping off days that can't be picked