# DateCalendar

> Month grid for picking one date (WAI-ARIA date picker grid).

Source: https://ui.jcsoftdev.com/docs/components/date-calendar

Month grid for picking one date (WAI-ARIA date picker grid). Dates are "YYYY-MM-DD" strings
handled in UTC, so a day never shifts with the time zone. Arrows move by day and week,
Home/End to the week edges, PageUp/PageDown by month (Shift: year); Enter or Space picks.

## Import

```ts
import { DateCalendar } from "@jcsoftdev/ui/calendar";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/calendar/date-calendar`.

## Usage

```tsx
<DateCalendar value="2026-09-07" today="2026-09-10" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | Selected date, "YYYY-MM-DD". |
| `onSelect` * | `(date: string) => void` |  | Called with the "YYYY-MM-DD" date the person picks. |
| `min` | `string` |  | Earliest selectable date, "YYYY-MM-DD". |
| `max` | `string` |  | Latest selectable date, "YYYY-MM-DD". |
| `isDateDisabled` | `((date: string) => boolean)` |  | Extra dates that cannot be picked (holidays, taken days). |
| `locale` | `string` |  | BCP 47 locale for labels. Defaults to the `locale` UI string. |
| `weekStartsOn` | `0 \| 2 \| 1 \| 4 \| 3 \| 5 \| 6` |  | First day of the week, 0 (Sunday) to 6. Defaults from the locale: Monday for es-PE. |
| `today` | `string` |  | "YYYY-MM-DD" treated as today. Defaults to the viewer's local date. |
| `autoFocus` | `boolean` | `false` | Moves focus into the grid on mount (when it opens inside a popover). |
| `className` | `string` |  |  |
| `classNames` | `Partial<Record<DateCalendarPart, string>>` |  | Per-part classes merged with `cn`; consumer classes win. `className` still targets the root and is merged last. |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/calendar-datecalendar--default)
- [Spanish Starts On Monday](/storybook/?path=/story/calendar-datecalendar--spanish-starts-on-monday)
- [Keyboard Grid](/storybook/?path=/story/calendar-datecalendar--keyboard-grid)
- [Month End Clamps](/storybook/?path=/story/calendar-datecalendar--month-end-clamps)
- [Min Max And Disabled Dates](/storybook/?path=/story/calendar-datecalendar--min-max-and-disabled-dates)
- [Controlled](/storybook/?path=/story/calendar-datecalendar--controlled)

## Source

`packages/ui/src/calendar/date-calendar/date-calendar.tsx`