# Calendar

Canonical page: https://docs.ovok.com/native-sdk/guide/components/ui/calendar

`Calendar` is a presentational month picker exported from `@ovok/native/ui`. It
supports controlled or internal selection, month navigation, localized labels,
week-start configuration, disabled dates, and optional day markers. It does not
persist values or perform platform or network work.

```tsx
import { Calendar } from "@ovok/native/ui";

<Calendar
  selectedDate={selectedDate}
  onDateSelect={setSelectedDate}
  locale="en-GB"
  weekStartsOn={1}
  minDate="2026-01-01"
/>
```

Pass `selectedDate` to control selection; update it in `onDateSelect`. Without
`selectedDate`, the component keeps its own selection, initialized by
`defaultSelectedDate`. Month navigation is controlled by `visibleMonth` and
`onVisibleMonthChange`, or internally initialized by `defaultVisibleMonth`.
Selection callbacks return local calendar `Date` values. Date-only strings in
`YYYY-MM-DD` form are parsed as local calendar dates to avoid UTC day shifts.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `selectedDate` | `Date \| string \| null` | internal | Controlled selected day; `null` clears it |
| `defaultSelectedDate` | `Date \| string` | — | Initial selection for uncontrolled mode |
| `onDateSelect` | `(date: Date) => void` | — | Called when an enabled day is selected |
| `visibleMonth` | `Date \| string` | internal | Controlled month to display |
| `defaultVisibleMonth` | `Date \| string` | selected day or today | Initial month for uncontrolled mode |
| `onVisibleMonthChange` | `(month: Date) => void` | — | Called with the first day of the displayed month |
| `locale` | `string` | device locale | Locale for month, weekday, and accessible date labels |
| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` | First weekday, where 0 is Sunday |
| `minDate`, `maxDate` | `Date \| string` | — | Inclusive selectable date bounds |
| `isDateDisabled` | `(date: Date) => boolean` | — | Additional caller-defined disabled dates |
| `markers` | `readonly CalendarDayMarker[]` | `[]` | Static marked days |
| `getMarkerForDate` | `(date: Date) => CalendarDayMarker \| undefined` | — | Dynamic day marker, useful for composed calendars |
| `labelForDate` | `(date: Date) => string` | localized date | Override the accessible date label |
| `previousMonthLabel`, `nextMonthLabel` | `string` | “Previous month”, “Next month” | Accessible navigation button labels |
| `theme`, `slots` | `OvokThemeOverride`, `Partial<OvokUiSlots>` | Paper theme/default slot | Optional UI theme and primitive overrides |
| `testID` | `string` | `calendar` | Prefix for calendar and day test IDs |

`CalendarDayMarker` accepts `date`, optional `label`, `backgroundColor`, `color`,
and optional `rangePosition` (`single`, `start`, `middle`, or `end`) to draw a
continuous marked band. Every date and navigation control exposes an accessible
label; selected and disabled states are also exposed to assistive technology.