Skip to main content
@super-calendar/core is the shared engine the renderers are built on: date math, the selection model, event layout, recurrence, time-zone conversion, and the neutral theme tokens. Reach for it directly only when you want entirely custom UI. Most apps use the native or react-dom or Solid components, which already wrap all of this.
react is an optional peer dependency. The root entry imports React for its hooks. Import @super-calendar/core/vanilla when you need pure functions without React, including on a server or in a Solid app:
The vanilla entry exports the pure core types and helpers, excluding React hooks and providers. Existing @super-calendar/core imports continue to work.

Month grid

When you want your own day-cell markup but not the date maths, useMonthGrid gives you the grid as data: the weeks, the weekday headers, and per-day state (today, selected, in-range, disabled, current-month). You render whatever you like.

Per-day state

Each day in weeks[].days carries: useMonthGrid(month, options) accepts weekStartsOn, showSixWeeks, isRTL, locale, selectedDates, selectedRange, and the minDate / maxDate / isDateDisabled constraints.
Need the grid outside React (tests, server, exports)? Call the pure buildMonthGrid(month, options); useMonthGrid is just a memoized wrapper around it. buildMonthWeeks(month, weekStartsOn) returns the raw Date[][].
layoutMonthWeek(days, events) lays one week row’s events out as spanning bars: each event becomes a single segment carrying the startCol / endCol it covers, a lane for stacking overlapping events, and continuesBefore / continuesAfter flags for bars that run past the row’s edges. It’s the same layout the built-in month grid uses, so a custom month cell can draw identical multi-day bars.

Laying out timed events

layoutDayEvents(events, day) resolves overlaps into side-by-side columns for a day/week grid — the same math the TimeGrid uses, with no rendering opinion. Each PositionedEvent gives you placement:
startHours is the clock time, not the time elapsed since midnight, so on a daylight saving change day an event still lines up with its hour label. To place your own marks the same way, use wallClockHours(date, dayStart, nextDayStart), which reads the clock and clamps to the day (the closing midnight reads 24). clockHoursBetween(from, to) gives the rows a span covers: 01:30 to 03:30 is 2 even on a spring-forward day, when only 1 hour passes. To bucket events by calendar day (for a month or agenda), use groupEventsByDay(events) — a Map keyed by startOfDay(date).toISOString() that indexes multi-day events under every day they span. eventDayKeys(event) returns those keys for a single event.

More in core

Every helper below is pure (safe in tests, on a server, or in a worker). See the TypeScript types for exact signatures.
  • Drag math — cellRangeFromDrag (a sweep to start/end), resolveDraggedBounds (a move/resize to snapped bounds), clampMoveStartMinutes (holds a moved start inside the visible hour window), snapDeltaMinutes, shiftMinutes, movedClockSpan (where a move previews on a daylight saving change day).
  • Event display — eventTimeLabel, eventAccessibilityLabel, titleNumberOfLines / titleEllipsizeMode, isTimeVisibleAtHeight, formatHour (the shared time-grid hour-axis label both renderers default to).
  • Labels — resolveCalendarLabels fills a partial labels object with the English defaults; dayAccessibilityLabel builds a day label from a formatted date and its state words. Pass the resolved labels to eventAccessibilityLabel to localize a custom renderer’s event label the same way.
  • Month overflow — monthEventCapacity + monthVisibleCount decide how many chips fit before a “+N more” row.
  • Business hours — closedHourBands(day, businessHours, minHour?, maxHour?) returns the hour spans to shade.
  • Presentation — rangeBandKind, bandRounding, dayBadgeKind map a day’s selection state to pill/badge intent (exactly what both renderers consume).
  • Selection — the useDateRange hook, plus pure nextDateRange, daySelectionState, isDateSelectable, isRangeEndpoint, isWithinDateRange.
  • Dates — getViewDays, getWeekDays, getIsToday, isWeekend, isSameCalendarDay, minutesIntoDay, isAllDayEvent.
  • Theme tokens — lightColors / darkColors (the neutral CalendarColors palette) to build a theme from scratch.
Recurrence (expandRecurringEvents) and time zones (eventsInTimeZone, toZonedTime) are pure core helpers too; see the Recurring events and Time zones guides.