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

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, the scrolling picker. See the Date selection guide.

Display

Prop	Type	Notes
scrollOffsetMinutes	number	Initial vertical scroll.
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).
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.
styles	Partial<Record<CalendarSlot, StyleProp>>	Per-slot style overrides, merged last.

Exports

Components

Calendar, Agenda, MonthView, YearView, MonthPager, MonthList, TimeGrid, ResourceTimeline, DefaultEvent, DefaultMonthEvent

Hooks

useDateRange, useMonthGrid, useCalendarTheme, useNow, useEventSource

Theming

defaultTheme, darkTheme, mergeTheme, CalendarThemeProvider, useCalendarTheme

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

Types

CalendarEvent, CalendarMode, RenderEventArgs, RecurrenceRule, BusinessHours, EventDragHandler, CalendarTheme, PositionedEvent, DateRange, MonthGrid, MonthEventSegment, MonthWeekEvents, MonthListProps, CalendarSlot, SlotStyleProps

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.

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.