API reference

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. The Solid 2 renderer shares the React DOM prop names and uses Solid JSX and accessors. Its exports are listed below. 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

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

DOM onChangeDate edge paging requires a mouse drag. Touch and pen retain in-view dragging without edge paging. Other navigation remains available.

​

Events & rendering

​

Interactions

DOM Calendar and TimeGrid accept touchDragDelay and touchDragThreshold. The delay is in milliseconds (default 300), and the threshold is in pixels (default 8). They control held event dragging and do not apply to native. Additional contacts cancel pending holds and cannot take over an active drag. See DOM held presses. 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. After native edge paging, a floating event’s horizontal centre selects the destination day, and its top edge selects the time. CalendarEvent.dragHandleColor?: string overrides an event’s native resize grip colour in TimeGrid and both orientations of ResourceTimeline. It defaults to theme.colors.eventText; showDragHandle={false} still hides time-grid grips. Changing showDragHandle updates mounted native time-grid grips even when events is unchanged. The DOM renderer has no visible resize grips. DOM onPressCell also handles touch taps on empty time-grid slots. The callback runs from the column’s click, after pointer-up. Swipes and cancelled contacts do not call it. Mouse and pen retain their existing behavior. renderCreateGhost is a component (ComponentType in React, Component in Solid) that receives CreateGhostArgs: { start: Date; end: Date }. These are the snapped, ordered range onCreateEvent would receive if the sweep ended at the current pointer position, clamped to the pressed day. The range can extend past a narrowed minHour/maxHour window, while the web preview box stops at the visible edge. It renders only while onCreateEvent is set and never enables creation itself. TimeGrid, Calendar (time-grid modes), and ResourceTimeline accept it on every renderer; ResourceTimeline adds the lane’s resource. Web previews follow scrolling and zooming while the pointer is held. Cancelled native gestures do not call onCreateEvent. The content is clipped to the preview, non-interactive, and hidden from assistive tech. On React Native it updates when the sweep crosses a snap step. See Show a draft in the preview.

​

Selection

The same props drive MonthList, the scrolling picker. See the Date selection guide.

​

Display

Month Calendar, MonthView, and MonthList accept chipHeight and chipGap. Both are numbers in pixels. DOM height defaults to 18; native height follows the theme. The gap defaults to 2 on both renderers. Native MonthPager forwards them too. Changing either dimension updates already mounted list and pager months.

​

Exports

​

Core-only helpers

Import @super-calendar/core/vanilla to use pure core types and helpers without React. The root entry still exports those helpers plus the existing React hooks and selection provider. React is an optional package peer but is required when you import the root entry. loadEventSource({ source, format?, map?, signal? }) loads one JSON/iCalendar batch or calls an async event loader. It returns Promise<CalendarEvent<T>[]> and rejects HTTP, validation, and cancellation errors. signal applies to URL requests. The default mapper validates calendar fields and converts event and recurrence dates. A custom mapper owns its field validation. This helper and the EventSource<T> and EventSourceOptions<T> types are exported from both core entries and from @super-calendar/solid. @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. wallClockHours(date, dayStart, nextDayStart) converts a time to its time-grid row in fractional clock hours, clamped to the day. layoutDayEvents and backgroundBandsForDay use it, so on a daylight saving change day events line up with their hour labels rather than shifting by the hour the clock skipped or repeated. clockHoursBetween(from, to) returns how many rows a span covers: the elapsed hours plus any daylight saving offset change between the two. Inside the hour a fall-back change repeats, where that would come out zero or negative, it returns the elapsed hours instead. 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. Each edge moves on the clock with shiftMinutes; when the resulting clock time occurs twice, in the hour a fall-back change repeats, the occurrence nearer the elapsed shift wins. For a live preview of the same move, movedClockSpan(start, end, minutes) returns how far the start moves in clock hours and how many rows the moved span covers, at least the layout’s minimum box. A resize moves the end to the clock time its drawn edge is dragged to. That edge is what drawnEnd(start, end) returns: the end itself, except for a span whose clock runs backwards in the repeated hour, which is drawn its elapsed length from its start.

​

Shared web behavior

React DOM and Solid MonthList apply callback, date-constraint, theme, and slot updates to mounted months, even when date and events keep the same references. DatePicker and DateRangePicker apply theme to both the picker chrome and the nested calendar, including updates while open. Per-slot styles take precedence. Setting disabled closes an open popover and prevents date changes. Re-enabling the field leaves the popover closed until you open it again. Opening a picker moves focus to the selected day, today, or the first available day in that month. If the month has no available days, the popover panel receives focus; Escape closes it and returns focus to the trigger. Web TimeGrid and ResourceTimeline expose Edit events when visible events can be edited. Choose an event to open move and resize actions, an alternative to dragging for keyboard, click, and tap. The actions call onDragEvent with the same bounds a drop would, so eventOverlap, draggable, startEditable, durationEditable, and a false return apply. Style it with the eventActionsTrigger, eventActionsList, eventActions, and eventAction slots. Long choosers scroll without shrinking their choices. Choices and dialogs wrap titles without spaces. The action dialog is centered in the viewport by default. The optional editEvents and eventActions(title) labels name the chooser and event actions. eventChangeRejected supplies the polite status message for rejected edits (default “This change is not allowed.”). Both web ResourceTimeline components accept labels. Web Calendar, TimeGrid, and ResourceTimeline accept the optional getEventId: (event) => string | number prop to keep editing through full event-array refreshes. IDs must be stable and unique per occurrence. Missing, invalid, or duplicate IDs close the dialog. Without this prop, full refreshes close it. The chooser and dialog include both dates for multi-day events. PageUp and PageDown inside the dialog do not change the calendar page. See Move and resize actions.

​

Solid exports

@super-calendar/solid is an ESM package for solid-js@2.0.0-rc.20 and @solidjs/web@2.0.0-rc.20. Its version matches the other calendar packages, and it uses the latest npm tag. It does not support Solid 1. The Solid guide covers compiler setup and hydration. Component props and slot types are exported with their component names, such as CalendarProps<T> and TimeGridSlot. Custom renderers use SolidRenderEvent<T>, SolidMonthEvent<T>, SolidAgendaEvent<T>, and their Args types. ResourceEventArgs<T>, Resource, CSSProperties, SlotStyleProps, ResolvedSlot, SlotDefault, DateRangeOptions, NowOptions, and the Solid EventSourceState<T> are also exported. Render callbacks return JSX.Element from @solidjs/web. Calendar takes renderTimeEvent, renderMonthEvent, and renderScheduleEvent. Direct views take renderEvent. Read renderer props inside JSX to preserve reactivity. The Solid guide includes complete examples for custom events, date pickers, and resource timelines. Calendar and TimeGrid accept a callback ref receiving CalendarHandle. scrollToTime(minutes, options?) scrolls the mounted time grid. It has no effect after disposal or while Calendar displays another type of view. React DOM and Solid ResourceTimeline event buttons support keyboard activation, including when dragging is enabled. draggable: false blocks moves and resizes while preserving activation. Removing the active event or resource lane, losing pointer capture, or unmounting cancels a gesture without a drop callback. expandRecurringEvents stops at JavaScript’s date limits and omits occurrences whose end date would overflow. createEventSource starts on the client, retains the last successful batch on errors, and aborts superseded URL requests. It stops polling on disposal and ignores later refetch calls. Finite refetchIntervalMs values greater than zero and no larger than 2147483647 ms enable polling; other values disable it. Custom async functions cannot be aborted, but their stale results are ignored. The package re-exports shared event, selection, grid, recurrence, iCalendar, and label types and helpers. Import @super-calendar/core/vanilla for the complete pure helper set. React hooks and providers are not exported by the Solid package.