@super-calendar/core

The render-agnostic core of super-calendar: date math, the selection model, event layout, the month-grid builder, the headless hooks, and the neutral theme tokens.

It imports nothing from React Native, react-dom, Reanimated, Gesture Handler, or Legend List, so it bundles into any renderer. Use it to drive your own UI, or pair it with @super-calendar/dom (react-dom) or @super-calendar/native (React Native).

Install

npm install @super-calendar/core

Also on JSR: deno add jsr:@super-calendar/core.

Peer dependencies: date-fns (>=3) and react (>=19).

Usage

Build a fully custom month grid from the headless useMonthGrid hook. It returns the weeks, the weekday headers, and per-day state for you to render however you like.

import { useMonthGrid } from "@super-calendar/core";

function MyGrid({ month }: { month: Date }) {
  const { weeks, weekdays } = useMonthGrid(month, { weekStartsOn: 1 });

  return weeks.map((week) =>
    week.days.map((day) => (
      // day carries isToday / isSelected / isInRange / isDisabled / isCurrentMonth
      <DayCell key={day.date.toISOString()} day={day} />
    )),
  );
}

Manage single, multiple, or range selection with useDateRange:

import { useDateRange } from "@super-calendar/core";

const range = useDateRange({ mode: "range" });

For a custom time-grid drag, clampMoveStartMinutes keeps the moved event's start inside the visible hour window while allowing its unchanged duration to carry the end past midnight:

import { clampMoveStartMinutes } from "@super-calendar/core";

const startMinutes = clampMoveStartMinutes(rawStartMinutes, minHour, maxHour, snapMinutes);

To position your own marks on a time grid, wallClockHours(date, dayStart, nextDayStart) returns the fractional clock hour, clamped to the day. It matches layoutDayEvents, which places events by clock time so they line up with the hour labels on a daylight saving change day. clockHoursBetween(from, to) returns how many rows a span covers.

Use resolveDraggedBounds to commit a move or resize. Equal start and end deltas move the event while preserving elapsed duration, including across daylight saving changes. For a resize, pass zero for the edge you want to keep fixed.

CalendarEvent<T> includes an optional dragHandleColor: string for the native renderer's time-grid and resource-timeline resize grips. When omitted, those grips use theme.colors.eventText. Core preserves the field without interpreting it.

Documentation

See the full documentation and the API reference.

License

MIT