Browse docs

Calendar

Calendar is a standalone, inline month grid for picking a single date. It is a primitive — always visible, no popup, no form-bridge or RBAC integration. For a form-bound date field use DatePicker, which pairs an input with a Calendar popup.

Dates are plain ISO YYYY-MM-DD strings throughout — no time, no time zone. The month grid, keyboard navigation, and localization come from the headless @dashforge/calendar-core engine; Calendar is the MUI presentation layer over it.

Quick Start

tsx

import { Calendar } from '@dashforge/ui';

<Calendar
  defaultValue="2026-05-20"
  onChange={(iso) => console.log(iso)}
/>

Examples

A basic uncontrolled calendar — defaultValue seeds the selection, the grid manages it from there.

May 2026

Sun

Mon

Tue

Wed

Thu

Fri

Sat

<Calendar defaultValue="2026-05-20" />

Constrained dates

minDate / maxDate bound the selectable range; disabledDates blocks specific days. isDateDisabled (a predicate) covers rule-based cases such as "weekdays only".

May 2026

Sun

Mon

Tue

Wed

Thu

Fri

Sat

<Calendar
  defaultValue="2026-05-15"
  minDate="2026-05-04"
  maxDate="2026-05-29"
  disabledDates={['2026-05-12', '2026-05-13', '2026-05-20']}
/>

Week start & locale

weekStartDay sets the first column (0 = Sunday, 1 = Monday). locale is a BCP-47 tag driving the month and weekday names.

May 2026

Mon

Tue

Wed

Thu

Fri

Sat

Sun

<Calendar defaultValue="2026-05-20" weekStartDay={1} locale="en-GB" />

Controlled

Pass value + onChange to own the selection in your own state.

May 2026

Sun

Mon

Tue

Wed

Thu

Fri

Sat

Selected: 2026-05-20

const [date, setDate] = useState<string | null>('2026-05-20');

<Calendar value={date} onChange={setDate} />

API

Prop	Type	Default	Description
`value`	`ISODate \| null`	—	Selected date (controlled).
`defaultValue`	`ISODate \| null`	`null`	Initial selected date (uncontrolled).
`onChange`	`(value: ISODate) => void`	—	Fired when a day is chosen.
`month` / `year`	`number`	—	Controlled displayed month (1-indexed) + year.
`defaultMonth` / `defaultYear`	`number`	from value / today	Initial displayed month + year (uncontrolled).
`onMonthChange`	`(month, year) => void`	—	Fired when the displayed month changes.
`minDate` / `maxDate`	`ISODate`	—	Selectable range bounds (inclusive).
`disabledDates`	`ISODate[]`	—	Explicit list of disabled dates.
`isDateDisabled`	`(date: ISODate) => boolean`	—	Predicate disabling arbitrary dates.
`weekStartDay`	`WeekDay`	`0`	First-column weekday (`0` = Sunday).
`locale`	`string`	`'en-US'`	BCP-47 locale for month / weekday names.
`today`	`ISODate`	host date	Overrides "today" — mainly for testing.
`disabled`	`boolean`	`false`	Disables the whole calendar.
`autoFocus`	`boolean`	`false`	Moves DOM focus to the active day cell on mount.
`aria-label`	`string`	`'Calendar'`	Accessible label for the grid.
`testId`	`string`	—	Test id applied to the root element.

ISODate is a YYYY-MM-DD string; WeekDay is 0 \| 1 \| … \| 6. Both come from @dashforge/calendar-core.

Accessibility

Implements the WCAG grid pattern — role="grid" with row / columnheader / gridcell structure.
Roving tab-index: one day cell is tabbable at a time; arrow keys move focus across the grid and over month edges, Enter / Space selects.
The current day carries aria-current="date"; the selected day carries aria-pressed.

Notes

Primitive, not a field. Calendar has no name, no validation, no RBAC. It does not register with DashForm. Use DatePicker for form integration.
ISO YYYY-MM-DD only. No time component and no time zone — a stored date never drifts across zones or DST.
Headless core. The grid math and keyboard model live in @dashforge/calendar-core; the same engine powers the Tailwind Calendar in @dashforge/tw.