Calendar
A date field component that allows users to enter and edit dates.
Basic Calendar
Selected: Thu May 21 2026
Date Range
Select a range of dates.
Range: Thu May 21 2026 - Thu May 28 2026
Disabled Dates
Disable past dates or specific dates.
Usage
import { Calendar } from "@/components/ui/calendar"
const [date, setDate] = React.useState<Date | undefined>(new Date())
{/* Single date */}
<Calendar
mode="single"
selected={date}
onSelect={setDate}
/>
{/* Date range */}
<Calendar
mode="range"
selected={dateRange}
onSelect={setDateRange}
numberOfMonths={2}
/>
{/* Disabled dates */}
<Calendar
mode="single"
disabled={(date) => date < new Date()}
/>Sidecar
The Markdown sidecar Studio (and the Grade MCP server, when it ships) reads to understand this component — frontmatter, when- to-use guidance, and canonical examples. Authored once at packages/ui/components/ui/calendar.md and shipped inside the published @gradeui/ui tarball.
---
name: Calendar
import: "@gradeui/ui"
subcomponents: [CalendarDayButton]
props:
- mode?: "single" | "multiple" | "range" — picks one date, several dates, or a [from, to] range
- selected?: Date | Date[] | { from: Date; to?: Date } — controlled selection; shape matches `mode`
- onSelect?: (value) => void — fires with the new selection
- month?: Date — controlled displayed month
- defaultMonth?: Date — uncontrolled initial month
- onMonthChange?: (date: Date) => void
- numberOfMonths?: number (default 1) — render multiple months side by side, useful for range pickers
- disabled?: Date | Date[] | { before?: Date; after?: Date } | (date: Date) => boolean
- captionLayout?: "label" | "dropdown" | "dropdown-months" | "dropdown-years"
- className?: string
when_to_use: An inline date grid — date-of-birth pickers in profile forms, scheduling screens with a month view, range selection in reporting filters. For a compact trigger-and-popover input, use DatePicker / DateRangePicker (which wrap Calendar internally). For one-off relative dates ("yesterday", "last week") use a Select instead.
composes_with: [Popover (DatePicker composes them), Card (inline scheduling card), Dialog (full-screen mobile date pick)]
aliases: [calendar, date grid, month view, scheduler grid, calendar view, multidate picker, react native calendars]
---
```jsx
// Single-date inline calendar.
<Calendar
mode="single"
selected={date}
onSelect={setDate}
captionLayout="dropdown"
/>
```
```jsx
// Two-month range picker — typical reporting filter shape.
<Calendar
mode="range"
numberOfMonths={2}
selected={range}
onSelect={setRange}
/>
```