shadcn-syntax-calendar-datepicker

name	shadcn-syntax-calendar-datepicker
description	Use when adding, customising, or debugging a shadcn ui Calendar or Date Picker, choosing between the three react-day-picker v9 selection modes (single / multiple / range), typing the `selected` state and the `onSelect` callback for each mode (Date vs Date[] vs DateRange), wiring a DatePicker by composing Calendar inside a Popover with a Button trigger that formats the date via date-fns, localising the calendar to Dutch / German / French via the `dateLib` adapter, disabling specific dates with a `disabled` matcher or a date-fns predicate, styling the calendar via `classNames` + `modifiers` + `modifiersClassNames`, swapping the day renderer through the `components` prop, or migrating an existing Calendar file from react-day-picker v8 to v9 after running `shadcn add calendar --overwrite`. Prevents the canonical Calendar failures : omitting the required `mode` prop so TypeScript narrows `selected` to `undefined` and the calendar never marks any day as selected, importing v8-only props (`selectedDays`, `disabledDays`, `fromDate`, `toDate`, `fromMonth`, `toMonth`, `numberOfMonths` typing) that no longer exist on the v9 surface, declaring `useState<Date>()` and then passing the setter to `mode="range"` which expects `DateRange | undefined`, forgetting `"use client"` at the top of any file that mounts a Calendar so the `Intl.DateTimeFormat()` call inside react-day-picker triggers a hydration mismatch in Next.js App Router, hand-styling individual day cells with arbitrary Tailwind instead of routing through `classNames.day` / `modifiers` so future `shadcn add calendar --overwrite` runs nuke the customisation, and treating DatePicker as a single importable primitive when it is a documented Popover + Button + Calendar recipe with no `<DatePicker />` export. Covers the v9 Mode union (`"single" | "multiple" | "range"`), exact selected/onSelect type per mode, the DateRange type (`{ from: Date | undefined; to?: Date | undefined }`), the v8 -> v9 prop renames (`fromMonth`/`fromYear` -> `startMonth`, `toMonth`/`toYear` -> `endMonth`, `fromDate`/`toDate` -> `hidden` + before/after matcher, `Caption` -> `MonthCaption`, `Row` -> `Week`, `HeadRow` -> `Weekdays`, `IconLeft`/`IconRight` -> single `Chevron`, `day_selected` -> `selected`, `day_disabled` -> `disabled`), the shadcn Calendar wrapper props (`buttonVariant`, `captionLayout`, `showOutsideDays`, `formatters`, `components`), the locked-down `classNames` keys exposed by `getDefaultClassNames()`, the Popover + Button DatePicker recipe for single / range / preset variants, the date-fns `format(..., "PPP")` and `format(..., "LLL dd, y")` trigger-label patterns, locale wiring via the v9 dateLib adapter and `date-fns/locale/nl`, RSC safety (`"use client"` mandatory), and the forward pointer to `shadcn-errors-react-day-picker-v9` for recovery from the v8 -> v9 silent breakage. Keywords: shadcn calendar, shadcn date picker, datepicker, Calendar component, DatePicker recipe, react-day-picker v9, react-day-picker v8 to v9, DayPicker, mode single, mode multiple, mode range, DateRange type, onSelect callback, selected Date undefined, calendar disabled dates, fromDate toDate, startMonth endMonth, captionLayout dropdown, dateLib adapter, locale nl date-fns, getDefaultClassNames, classNames day selected, modifiers modifiersClassNames, CalendarDayButton, components prop, custom day renderer, Chevron orientation, MonthCaption, Popover Calendar Button, asChild PopoverTrigger, format PPP, format LLL, Pick a date placeholder, numberOfMonths range, defaultMonth, showOutsideDays, hydration mismatch Intl DateTimeFormat, use client Calendar, shadcn add calendar overwrite, calendar v9 breaking change, selectedDays renamed, fromDate hidden before after matcher, how do I make a date picker, how do I disable past dates, how do I localize the calendar, calendar nothing selected, range from to optional, DateRange from undefined.
license	MIT
compatibility	Designed for Claude Code. Requires shadcn ui evergreen-2026 with react-day-picker v9 (BREAKING change from v8). For v8 -> v9 recovery, see shadcn-errors-react-day-picker-v9.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

shadcn ui : Calendar + DatePicker Syntax

The shadcn Calendar is a thin wrapper over react-day-picker v9 (DayPicker re-exported as Calendar). The DatePicker is NOT a primitive : it is a documented composition of Popover + Button (as PopoverTrigger asChild) + Calendar (inside PopoverContent). Every other "date input" pattern (preset shortcuts, range pickers, date+time hybrids) derives from this recipe.

The single most common failure on this primitive is the silent v8 -> v9 break : the API was redesigned mid-2025 (issue #4366, 97 reactions). Old Calendar source files that pre-date shadcn v4.x will silently misbehave on react-day-picker@9.0.0. Recovery is shadcn add calendar --overwrite. See Companion : shadcn-errors-react-day-picker-v9 for the full migration playbook.

Quick Reference

Canonical Calendar call

"use client"

import * as React from "react"
import { Calendar } from "@/components/ui/calendar"

export default function CalendarDemo() {
  const [date, setDate] = React.useState<Date | undefined>(new Date())

  return (
    <Calendar
      mode="single"
      selected={date}
      onSelect={setDate}
      =
      =
    />
  )
}