Calendar

Usage

Controlled inline month grid. onChange is required — a bare <Calendar /> renders but throws TypeError on the first day-cell click (or Enter/Space in the grid).

import { Calendar } from '@epasslive/design-system'
import * as React from 'react'

export function EventDate() {
  const [date, setDate] = React.useState<Date>(new Date())
  return <Calendar value={date} onChange={setDate} ariaLabel="Event date" />
}

When to use

• Standalone labelled date field in a form (filters, settings, checkout) → DatePicker: the browser UA owns the calendar popup, keyboard navigation and locale rendering; the value contract is ISO yyyy-mm-dd.
• Custom inline month grid (availability display, event-date explorer, a picker you compose yourself) → Calendar: the only DS molecule that draws the grid itself.
• Date-range filtering in dashboards → StatisticsDateFilter: the shipped range-filter surface. Do not compose Calendar into a range picker, and do not reach for DateRangePicker (planned, defective, no calendar ships).

Localization: English labels are the defaults, but every label is a prop — weekday headers (weekdayLabels, Monday-first), month names (monthLabels) and nav button names (prevMonthLabel/nextMonthLabel). Plain strings only — no Intl engine, week always Monday-first. For fully locale-aware date entry, use DatePicker — the browser UA owns month names, day names and first-day-of-week.

Accessibility

• Valid WAI-ARIA grid: role="grid" contains one header row of 7 columnheaders plus six week rows of 7 gridcells each (rows styled display: contents, visual layout unchanged). The grid is named by the aria-live="polite" month header via aria-labelledby; the outer wrapper is role="group" named by ariaLabel.
• Roving tabindex — single tab stop among day cells: ArrowLeft/Right ±1 day, ArrowUp/Down ±7 days, Home/End week bounds (Monday–Sunday), PageUp/PageDown ±1 month (day-clamped), Enter/Space select. DOM focus follows keyboard moves only; crossing a month boundary moves the view; clicking a cell also moves the roving cursor.
• Day cells carry aria-selected; disabled cells are aria-disabled — focusable for roving tabindex but never activatable (APG guidance). WCAG AA contrast in both themes.
• Known limitations: labels are plain strings (no Intl engine, week always Monday-first); the ‹ › nav buttons are not gated by minDate/maxDate; no year-level navigation; day cells use the browser default focus ring.

Props