Calendar

Selection Modes

Use mode="single" for simple date fields (appointments, birthdays). Use mode="range" with numberOfMonths={2} for booking flows so users see start and end in context. Use mode="multiple" sparingly - only when users genuinely need to pick several discrete dates.

Navigation & Layout

Use captionLayout="dropdown" when users may need to jump to distant months or years (e.g. date of birth). Use the default captionLayout="label" when navigation is typically within a few months of today. For range selection, display numberOfMonths={2} on desktop and fall back to a single month on mobile.

Responsive Behavior

The calendar grid uses --cell-size (defaults to 32px) for day cells. On mobile, ensure the calendar fits within the viewport width. Multi-month layouts stack vertically on narrow screens via flex-col md:flex-row. When placed inside a Popover, the calendar auto-positions to avoid overflow.

Timezone Handling

If users report off-by-one date selection (selecting the 20th highlights the 19th), set the timeZone prop to the user's local timezone using Intl.DateTimeFormat().resolvedOptions().timeZone. This ensures the calendar interprets midnight boundaries correctly across timezones.

Keyboard Navigation

• Arrow Left / Arrow Right — Move focus to the previous/next day
• Arrow Up / Arrow Down — Move focus to the same day in the previous/next week
• Page Up / Page Down — Navigate to the previous/next month
• Home / End — Jump to the start/end of the current week
• Enter or Space — Select the focused date

Screen Reader Support

• Built on React DayPicker which provides full ARIA grid semantics
• Each day cell is announced with its full date and selection state
• Month/year navigation announces the new visible month
• Disabled dates are announced as unavailable via aria-disabled
• Use aria-label on the calendar to provide context (e.g. "Select departure date")

Focus Management

Visible focus ring with 3px width using ring-ring/50 and ring-[3px]. Focus is automatically moved to the selected or focused day cell. When navigating months, focus transfers to the same day number in the new month (or the last available day if the month is shorter).

Touch Targets

Day cells are sized via --cell-size (default 32px) with aspect-square to maintain consistent hit areas. Navigation arrows use the same cell size for their touch target. For touch-heavy interfaces, increase the cell size via CSS custom property overrides.

ARIA Attributes

{/* Calendar with accessible label */}
<Calendar
  mode="single"
  selected={date}
  onSelect={setDate}
  aria-label="Select a date"
/>

{/* Disabled dates with screen reader context */}
<Calendar
  mode="single"
  selected={date}
  onSelect={setDate}
  disabled={(d) => d < new Date()}
  aria-describedby="date-constraint"
/>
<span id="date-constraint" className="sr-only">
  Only future dates can be selected
</span>

{/* Range calendar with descriptive label */}
<Calendar
  mode="range"
  selected={dateRange}
  onSelect={setDateRange}
  numberOfMonths={2}
  aria-label="Select check-in and check-out dates"
/>