Overview
April 2026
DatePicker and DateRangePicker — use Calendar directly when you need an always-visible calendar (not in a popover).
Need a calendar inside a popover trigger? Use
DatePicker instead. Calendar is for always-visible inline calendar UIs.Installation
Usage
Variants
Single Date Selection
April 2026
Date Range Selection
April 2026
With Disabled Dates
API Reference
string
required
Selection mode. Values:
single · multiple · rangeDate | Date[] | DateRange | undefined
Controlled selected value. Type depends on
mode.(date) => void
Callback fired when selection changes. Argument type matches
mode.Date
The month shown on initial render.
number
default:"1"
Number of months to display side by side (useful for range selection).
Matcher | Matcher[]
Rules for disabled dates. Accepts:
Date, DateRange, DayOfWeek, Before, After, or a function (date: Date) => boolean.Date
The earliest navigable and selectable month.
Date
The latest navigable and selectable month.
boolean
default:"false"
Auto-focus the calendar on mount — required when used inside a
Dialog or Popover.number
default:"0"
Day the week starts on.
0 = Sunday, 1 = Monday.Accessibility
- Calendar grid uses
role="grid"with column headers labeled by weekday abbreviation - Each day cell has
role="gridcell"witharia-selectedandaria-disabled - Navigation buttons are labeled “Go to previous month” / “Go to next month”
- Keyboard: Arrow keys move focus between days, Enter/Space selects, Page Up/Down navigates months
Do’s & Don’ts
Do
- Use
initialFocuswhen placing Calendar inside a Dialog or Popover - Use
numberOfMonths={2}for range selection to show both start and end months - Use
disabledprop to prevent selection of past dates, weekends, or holidays - Show a clear visual distinction between range start, range middle, and range end
Don't
- Don’t use Calendar inline inside a form field — use
DatePickerinstead - Don’t display more than 3 months side by side — it becomes too wide on mobile
- Don’t forget
initialFocusin modal contexts — keyboard users will be stuck outside - Don’t use
mode="multiple"for date ranges — usemode="range"instead