# rn-mini-calendar
URL: /docs/native/docyrus/mini-calendar

Compact date picker calendar with month navigation, locale-aware names, marked-date dots and a Today shortcut.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-mini-calendar
```

Month and weekday names come from `Intl` using the device locale. When the optional `react-native-localize` is installed it is used to detect that locale (it needs its Expo config plugin in `app.config.ts`); without it the `Intl` default locale is used.

## Usage

```tsx
import { MiniCalendar } from '@/components/docyrus-native/mini-calendar';

const [date, setDate] = useState<Date | undefined>();

```

### Marked dates (dot indicators)

```tsx

```

### Disabling days

```tsx

```

`disabledDates` accepts the same matchers as [rn-day-picker](/docs/native/docyrus/day-picker) `disabled`.

### Translations

The Today button reads `ui.miniCalendar.today` from `<UiTranslationProvider>` (fallback `Today`); `messages.today` wins over it. The navigation buttons use `ui.miniCalendar.previousMonth` / `ui.miniCalendar.nextMonth` as accessibility labels.

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `Date` | — | Currently selected date. When it moves to another month, the calendar follows. |
| `onChange` | `(date: Date) => void` | — | Called when a date (or Today) is pressed |
| `minDate` | `Date` | — | Minimum selectable date |
| `maxDate` | `Date` | — | Maximum selectable date |
| `disabled` | `boolean` | `false` | Disable all interactions |
| `disabledDates` | `Matcher \| Matcher[]` | — | Disable individual days |
| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` | First day of the week (0 = Sunday … 6 = Saturday) |
| `locale` | `string` | device locale | BCP-47 locale for month / weekday names |
| `markedDates` | `Date[]` | — | Dates to show dot indicators on |
| `markedDotColor` | `string` | theme primary | Custom color for dot indicators |
| `showTodayButton` | `boolean` | `true` | Show the Today shortcut button |
| `onMonthChange` | `(month: Date) => void` | — | Called with the first day of the newly visible month |
| `messages` | `MiniCalendarMessages` | — | App-supplied copy (wins over the translation provider) |
| `className` | `string` | — | Additional CSS classes |

### MiniCalendarMessages

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `today` | `string` | `t('ui.miniCalendar.today', 'Today')` | Today button label |

## Shared helpers

`mini-calendar` also exports the pure calendar-grid helpers used by `DayPicker` (and available to other calendar surfaces):

| Export | Signature | Description |
|--------|-----------|-------------|
| `getMonthWeeks` | `(year, month, { weekStartsOn?, showOutsideDays?, fixedWeeks? }) => CalendarGridDay[][]` | Month grid as weeks of 7 `{ date, outside, hidden }` cells |
| `getWeekdayNames` | `(weekStartsOn, locale?, format?) => string[]` | Localized weekday names rotated to `weekStartsOn` |
| `getMonthName` | `(monthIndex, locale?, format?) => string` | Localized month name |
| `dateMatchModifiers` | `(date, matchers) => boolean` | Whether a date matches a matcher / list of matchers |
| `createMarkedDateSet` | `(dates?) => Set<string> \| null` | Day-key set for O(1) marked-date lookups |
| `toDateKey` | `(date) => string` | `YYYY-M-D` day key |
| `isSameDay` | `(a, b) => boolean` | Calendar-day equality |
| `startOfDate` | `(date) => Date` | Local midnight of a date |

## Type Exports

| Type | Description |
|------|-------------|
| `MiniCalendarProps` | Props for MiniCalendar |
| `MiniCalendarMessages` | App-supplied copy |
| `WeekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` |
| `Matcher` | react-day-picker compatible day matcher |
| `DateRange`, `DateBefore`, `DateAfter`, `DateInterval`, `DayOfWeek` | Matcher shapes |
| `CalendarGridDay` | `{ date: Date; outside: boolean; hidden: boolean }` grid cell |

## Migration (breaking)

- `firstDayOfWeek?: 0 | 1` was replaced by `weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6` (same default: Monday).
- The Today label no longer reads `DocyThemeProvider.messages['mini-calendar.today']` or an embedded Turkish map — use `<UiTranslationProvider>` (`ui.miniCalendar.today`) or `messages.today`.