Skip to main content

Overview

April 2026
Calendar is a standalone month-view grid for selecting a date or date range. It is the underlying component used by 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 · range
Date | 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" with aria-selected and aria-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 initialFocus when placing Calendar inside a Dialog or Popover
  • Use numberOfMonths={2} for range selection to show both start and end months
  • Use disabled prop 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 DatePicker instead
  • Don’t display more than 3 months side by side — it becomes too wide on mobile
  • Don’t forget initialFocus in modal contexts — keyboard users will be stuck outside
  • Don’t use mode="multiple" for date ranges — use mode="range" instead