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 a trigger with a Calendar popover.

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; this Calendar is the Tailwind presentation layer over it — the same engine the MUI @dashforge/ui calendar renders.

Quick Start

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

<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.

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

<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".

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

<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.

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

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

Controlled

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

import { useState } from 'react';
import { Calendar, Stack, Typography } from '@dashforge/tw';

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

  return (
    <Stack gap={2} sx="items-center">
      <Calendar value={date} onChange={setDate} />
      <Typography variant="caption" sx="text-neutral-500">
        Selected: {date ?? '—'}
      </Typography>
    </Stack>
  );
}

API

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

Customization

sx overrides the root element's Tailwind classes; slotProps targets the inner slots.

<Calendar
  defaultValue="2026-05-20"
  sx="rounded-xl shadow-md"
  slotProps={{ day: { className: 'font-medium' } }}
/>

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 MUI Calendar in @dashforge/ui.
• Theme-identity clean. The day grid uses the neutral palette through dashforgePreset() — no dark: variants, so dark mode follows the CSS-var swap automatically.