> ## 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.

`<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.                       |
| `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).   |

## 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. |
| `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.      |
| `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.                                     |
| `onDragStart`           | `(event) => void`                        | Fires on grab (e.g. haptics).                                                     |
| `onCreateEvent`         | `(start, end) => void`                   | Drag empty space to create.                                                       |
| `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.                                                             |
| `onPressDay`            | `(date) => void`                         | Tap a month day cell.                                                             |
| `onPressMore`           | `(events, date) => void`                 | Tap the `+N more` overflow.                                                       |

## Selection

Date selection lives on [`MonthList`](/guides/month-list), not the paged `month`
view. It takes `selectedDates` / `selectedRange` (+ `onSelectDrag` for drag),
and `minDate` / `maxDate` / `isDateDisabled` for disabled days. See the
[Date selection](/guides/selection) guide.

## Display

| Prop                   | Type                                       | Notes                                                                           |
| ---------------------- | ------------------------------------------ | ------------------------------------------------------------------------------- |
| `scrollOffsetMinutes`  | `number`                                   | Initial vertical scroll.                                                        |
| `hourHeight`           | `number`                                   | Row height (px per hour).                                                       |
| `timeslots`            | `number`                                   | Hour sub-divisions.                                                             |
| `ampm`                 | `boolean`                                  | 12-hour labels.                                                                 |
| `showNowIndicator`     | `boolean`                                  | Current-time line (default on).                                                 |
| `showAllDayEventCell`  | `boolean`                                  | All-day lane (default on).                                                      |
| `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.                                   |
| `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`, `DEFAULT_HOUR_HEIGHT`
  </Card>

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