Calendar

A month grid for picking a day, several days or a range.

Source
$npx @dinachi/cli@latest add calendar
May 2026
June 2026
July 2026
August 2026
September 2026
October 2026
November 2026
December 2026
January 2027
February 2027
March 2027
April 2027
May 2027

Nothing picked

mode
layout
captionLayout
weekNumbers
disabled

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

May 2026
June 2026
July 2026
August 2026
September 2026
October 2026
November 2026
December 2026
January 2027
February 2027
March 2027
April 2027
May 2027

No day picked

One day, months scrolling as a column.
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>
  );
}

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"single" | "multiple" | "range" = "single"
One day, a set of days, or a from and to.
value
agent
Date | null | Date[] | DateRange
Controlled value. Its type follows mode.
defaultValueDate | null | Date[] | DateRange
Starting value when uncontrolled.
onValueChange
agent
(value, details) => void
Runs on every pick, for people and agents. details.cancel() refuses the change.
layout"scroll" | "paged" = "scroll"
Scroll months as a column, or page them with arrows.
numberOfMonthsnumber = 1
Months side by side in the paged layout.
captionLayout"label" | "dropdown" = "label"
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.
min
agent
Date
The earliest day that can be picked. Agents are refused before it.
max
agent
Date
The latest day that can be picked. Agents are refused after it.
isDateDisabled
agent
(date: Date) => boolean
Blocks single days, such as weekends. A range can't run across one.
disabled
agent
boolean = false
Blocks people and agents.
weekNumbersboolean = false
Shows week numbers before each week: ISO 8601 when weeks start on Monday, else the locale's.
localeLocale
A date-fns locale for month and weekday names.
weekStartsOn0 to 6 = 1
The first day of the week, 0 for Sunday. Defaults to the locale's.
dir"ltr" | "rtl"
Reading direction. Arrow keys follow it.
todayDate
Overrides the current day, for tests and other time zones.
onPreview(range: DateRange | null) => void
The range under the pointer while it waits for an end.
namestring
Submits the value with a form, as YYYY-MM-DD or YYYY-MM-DD/YYYY-MM-DD.
requiredboolean = false
A picked day can't be unpicked by pressing it again. The hidden input is not validated; use a picker for a required field.
autoFocusboolean = false
Focuses the picked day, or today, on mount.
allowDisabledEnd
agent
boolean = false
Lets a range end on the first disabled day after its start, as a stay checks out on a booked night. That day still can't start a range.
renderDay(date: Date) => ReactNode
Short content under a day's number, such as a price.
dayClassName(date: Date) => string | undefined
Classes for a day's button, such as a sold-out style.
describeDay(date: Date) => string | undefined
Words added to a day's name, such as "sold out", so it is heard as well as seen.

Agent

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

Reads

label

The calendar's aria-label.

value

YYYY-MM-DD, a list of them in multiple mode, or [from, to] for a range.

multiple

True in multiple and range modes, where the value is a list.

disabled

True when the calendar is blocked.

invalid

True 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.