@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:
@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
Eachday in weeks[].days carries:
useMonthGrid(month, options) accepts weekStartsOn, showSixWeeks, isRTL,
locale, selectedDates, selectedRange, and the minDate / maxDate /
isDateDisabled constraints.
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 —
resolveCalendarLabelsfills a partiallabelsobject with the English defaults;dayAccessibilityLabelbuilds a day label from a formatted date and its state words. Pass the resolved labels toeventAccessibilityLabelto localize a custom renderer’s event label the same way. - Month overflow —
monthEventCapacity+monthVisibleCountdecide 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,dayBadgeKindmap a day’s selection state to pill/badge intent (exactly what both renderers consume). - Selection — the
useDateRangehook, plus purenextDateRange,daySelectionState,isDateSelectable,isRangeEndpoint,isWithinDateRange. - Dates —
getViewDays,getWeekDays,getIsToday,isWeekend,isSameCalendarDay,minutesIntoDay,isAllDayEvent. - Theme tokens —
lightColors/darkColors(the neutralCalendarColorspalette) to build a theme from scratch.
expandRecurringEvents) and time zones (eventsInTimeZone,
toZonedTime) are pure core helpers too; see the
Recurring events and Time zones
guides.