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>
  );
}

Theme defaults

Configure <Calendar> defaults application-wide.

import { patchTheme } from '@dashforge/tw-theme';

patchTheme({
  components: {
    Calendar: {
      defaults: { weekStartDay: 1, locale: 'en-GB' },
    },
  },
});

Configurable axes (CalendarVariantProps):

Non-visual axes (value, defaultValue, onChange, month, year, minDate, maxDate, disabledDates, isDateDisabled, today, disabled, autoFocus) are per-instance — data and behavior — not theme-configurable.

Precedence chain (lowest → highest):

1. Built-in defaults (weekStartDay: 0, locale: 'en-US').
2. theme.components.Calendar.defaults (application-wide).
3. Instance prop (<Calendar weekStartDay={1} locale="fr-FR" />) — wins over theme.
4. sx — appended to the root and wins over conflicting classes via tailwind-merge.

TypeScript: theme.components.Calendar.defaults autocompletes to the two axes above.

Reactivity: useComponentDefaults('Calendar') subscribes to the theme store — patchTheme re-renders every mounted instance inheriting the changed axis.

API

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

Slots & slotProps

<Calendar> is a compound component with 4 named slots. Each slot accepts a { className?: string } override via slotProps:

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

Use sx for a root-level class override; use slotProps for a specific inner region (e.g. day hover color, header typography).

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.