> ## Documentation Index
> Fetch the complete documentation index at: https://super-calendar.afonsojramos.me/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> The main Calendar props and the package's exports.

This page documents `@super-calendar/native`. The react-dom renderer
(`@super-calendar/dom`) shares the same core types and views, with a few web-only
props and no React Native styling; see the [react-dom renderer](/guides/dom) guide
for its components and props.

The native package declares a React Native peer range of `>=0.74 <2`, which
includes stable 1.x versions. Use versions of Reanimated, Worklets, and Gesture
Handler that are compatible with your React Native version.

`<Calendar>` is the batteries-included entry point. The props below are the
common ones, grouped by purpose; every prop is typed via `CalendarProps<T>`, so
your editor lists the full set with inline docs.

## Data

| Prop | Type | Notes |
| - | - | - |
| `events` | `CalendarEvent<T>[]` | Your events. The generic `T` is your own data. |
| `date` | `Date` | The controlled anchor date, read in local time. |
| `mode` | `CalendarMode` | `month` `week` `day` `3days` `custom` `schedule`. |
| `numberOfDays` | `number` | Column count for `custom`. |
| `weekStartsOn` | `0–6` | 0 = Sunday, 1 = Monday. |
| `weekdayFormat` | `narrow \| short \| long` | Weekday header width (default `short`). |
| `timeZone` | `string` | Display events in this IANA zone (DST-correct). |

Anchor dates are read in the device's local time zone: construct `date` as a
local date (`new Date(2026, 7, 24)`), not a UTC instant. See
[time zones](/guides/time-zones#anchor-dates-are-local) for the off-by-one-week
pitfall this avoids.

## Navigation

| Prop | Type | Notes |
| - | - | - |
| `onChangeDate` | `(date) => void` | Fires when paging changes the date. |
| `onChangeDateRange` | `(range: [Date, Date]) => void` | The visible window — handy for fetching. |
| `freeSwipe` | `boolean` | Fling across several pages. |

## Events & rendering

| Prop | Type | Notes |
| - | - | - |
| `renderEvent` | `RenderEvent<T>` | Render events your way, every mode. |
| `eventAccessibilityLabel` | `(event, ctx) => string` | Override an event's screen-reader label. |
| `labels` | `Partial<CalendarLabels>` | Translate screen-reader words and actions. |
| `renderCustomDateForMonth` | `(date) => ReactNode` | Month: replace the day-cell date badge. |
| `eventCellStyle` | `style \| (event) => style` | Tweak the built-in box. |
| `calendarCellStyle` | `(date) => style` | Per-date column/cell shading. |
| `businessHours` | `(date) => { start, end } \| null` | Shade closed hours. |
| `renderBusinessHours` | `(band) => ReactNode` | Render closed-hours bands yourself. |
| `renderBackgroundEvent` | `RenderEvent` | Custom, pressable background bands. |
| `renderTimeGridHeader` | `(days) => ReactNode` | Replace the week/day day-header row. |
| `renderHeaderForMonthView` | `(weekDays) => ReactNode` | Replace the month weekday header. |
| `headerComponent` | `ReactNode` | Extra element between header and grid. |
| `keyExtractor` | `(event, index) => string` | Stable event keys. |

## Interactions

| Prop | Type | Notes |
| - | - | - |
| `onDragEvent` | `(event, start, end) => void \| boolean` | Enable move/resize; return `false` to reject. Month: drop on another day. |
| `onDragStart` | `(event) => void` | Fires on grab (e.g. haptics). |
| `onCreateEvent` | `(start, end) => void` | Drag empty space to create. Month and year: an all-day span. |
| `onSelectDrag` | `(start, end) => void` | Month and year: drag to sweep a date range; fires live. |
| `dragStepMinutes` | `number` | Snap step (default 15). |
| `showDragHandle` | `boolean` | Show the resize grip (default true). |
| `eventStartEditable` | `boolean` | Grid-wide: allow moving events (default true). Per-event `startEditable`. |
| `eventDurationEditable` | `boolean` | Grid-wide: allow resizing events (default true). Per-event `durationEditable`. |
| `eventOverlap` | `boolean` | When false, reject a drag/resize that would overlap another event (default true). |
| `onPressEvent` | `(event) => void` | Tap an event. |
| `onPressCell` | `(date) => void` | Tap empty grid space. Month: the tapped day at midnight. |
| `onPressDay` | `(date) => void` | Tap a month day cell. |
| `onPressMore` | `(events, date) => void` | Tap the `+N more` overflow. |

On the time grid, dragging any segment of a multi-day event moves its whole range.
All visible segments preview the move together on both renderers. Moving preserves
duration; resizing changes only the selected edge. See [dragging](/guides/dragging).

## Selection

| Prop | Type | Notes |
| - | - | - |
| `selectedDates` | `Date[]` | Discrete selected days (month + year). |
| `selectedRange` | `DateRange` | A selected span (month + year). |
| `fillCellOnSelection` | `boolean` | Month: fill the cell instead of the pill band. |
| `minDate` | `Date` | Earliest selectable day (inclusive). |
| `maxDate` | `Date` | Latest selectable day (inclusive). |
| `isDateDisabled` | `(date) => boolean` | Return true to forbid a specific day. |
| `onSelectDrag` | `(start, end) => void` | Drag to sweep a range; pair with `useDateRange`. |

The same props drive [`MonthList`](/guides/month-list), the scrolling picker. See
the [Date selection](/guides/selection) guide.

## Display

| Prop | Type | Notes |
| - | - | - |
| `scrollOffsetMinutes` | `number` | Vertical scroll in minutes; applied on mount and whenever it changes. |
| `hourHeight` | `number` | Row height (px per hour). |
| `minEventHeight` | `number` | Time grid: floor on an event box's height and its `boxHeight` (default 32). |
| `eventGap` | `number` | Time grid: inset between an event box and its slot, per side (default 2). |
| `timeslots` | `number` | Hour sub-divisions. |
| `ampm` | `boolean` | 12-hour labels. |
| `showNowIndicator` | `boolean` | Current-time line (default on). |
| `showAllDayEventCell` | `boolean` | All-day lane (default on; grows with all-day events, none when empty). |
| `showAllDayLabel` | `boolean` | Time grid: show the "all-day" text label (default off). |
| `refreshControl` | `ScrollViewProps["refreshControl"]` | Pull-to-refresh control for schedule, time-grid and year modes (React Native). |
| `allDayLabel` | `string` | Schedule all-day text ("All day"). |
| `highlightWeekends` | `boolean` | Tint weekend cells/columns (month + time grid, default on). |
| `maxVisibleEventCount` | `number` | Month: fixed cap on event lanes per week row. |
| `showTitle` | `boolean` | Month: the built-in "MMMM yyyy" label above the grid (default on). |
| `theme` | `PartialCalendarTheme` | Color/text/metric overrides. |
| `classNames` | `Partial<Record<CalendarSlot, string>>` | Per-slot Tailwind classes (uniwind/NativeWind); see [Styling](/guides/styling). |
| `styles` | `Partial<Record<CalendarSlot, StyleProp>>` | Per-slot style overrides, merged last. |

## Exports

<CardGroup cols={2}>
  <Card title="Components">
    `Calendar`, `Agenda`, `MonthView`, `YearView`, `MonthPager`, `MonthList`, `TimeGrid`,
    `ResourceTimeline`, `DefaultEvent`, `DefaultMonthEvent`
  </Card>

  <Card title="Hooks">
    `useDateRange`, `useMonthGrid`, `useCalendarTheme`, `useNow`, `useEventSource`
  </Card>

  <Card title="Theming">
    `defaultTheme`, `darkTheme`, `mergeTheme`, `CalendarThemeProvider`, `useCalendarTheme`
  </Card>

  <Card title="Helpers">
    `expandRecurringEvents`, `parseICalendar`, `toICalendar`, `eventsInTimeZone`, `toZonedTime`,
    `layoutDayEvents`, `layoutMonthWeek`, `isAllDayEvent`, `isBackgroundEvent`,
    `backgroundBandsForDay`, `buildMonthGrid`, `buildMonthWeeks`, `nextDateRange`,
    `isDateSelectable`, `isRangeEndpoint`, `isWithinDateRange`, `daySelectionState`, `getViewDays`,
    `getWeekDays`, `getIsToday`, `isWeekend`, `isSameCalendarDay`, `minutesIntoDay`,
    `weekdayFormatToken`, `defaultCalendarLabels`, `DEFAULT_HOUR_HEIGHT`
  </Card>

  <Card title="Types">
    `CalendarEvent`, `CalendarMode`, `RenderEventArgs`, `RecurrenceRule`, `BusinessHours`,
    `EventDragHandler`, `CalendarTheme`, `PositionedEvent`, `DateRange`, `MonthGrid`,
    `MonthEventSegment`, `MonthWeekEvents`, `MonthListProps`, `CalendarSlot`, `SlotStyleProps`,
    `CalendarLabels`, `CalendarHandle`, `ScrollToTimeOptions`
  </Card>
</CardGroup>

## Core-only helpers

`@super-calendar/core` also exports `clampMoveStartMinutes`. Use it when a custom
time-grid drag must keep the moved start inside the visible hour window without
shortening an event that continues past midnight.

For a custom renderer that should read like the built-in ones, `resolveCalendarLabels`
fills a partial `labels` object with the English defaults and
`dayAccessibilityLabel` joins a formatted date with its state words.

`resolveDraggedBounds` preserves elapsed duration when you pass the same minute
delta for both edges, including across daylight saving changes. The end's local
clock time can change to keep that duration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.