MiniCalendar

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

iOSAndroid

Preview MiniCalendar on your device

Scan with Expo Go

Download Expo Go, then scan the QR code to preview native components.

Installation

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

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

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

<MiniCalendar value={date} onChange={setDate} />
<MiniCalendar
  value={date}
  onChange={setDate}
  minDate={new Date(2024, 0, 1)}
  maxDate={new Date(2025, 11, 31)}
  weekStartsOn={0}
/>

Marked dates (dot indicators)

<MiniCalendar
  value={date}
  onChange={setDate}
  markedDates={taskDates}
  markedDotColor="#ef4444"
/>

Disabling days

<MiniCalendar
  value={date}
  onChange={setDate}
  disabledDates={[{ dayOfWeek: [0, 6] }, { before: new Date() }]}
/>

disabledDates accepts the same matchers as DayPicker 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.

MiniCalendar

On this page