# @super-calendar/core

> Render-agnostic core for super-calendar: date math, selection model, event layout, the month-grid builder, headless hooks, and neutral theme tokens. No renderer.

Latest version **2.14.1** (published 2026-10-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install @super-calendar/core
pnpm add @super-calendar/core
yarn add @super-calendar/core
bun add @super-calendar/core
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.14.1 |
| Published | 2026-10-20 |
| First published | 2026-06-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 335.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 192 |
| Maintainers | afonsojramos |
| Keywords | calendar, date-fns, date-picker, headless, react |

## Links

- npm: https://www.npmjs.com/package/@super-calendar/core
- Repository: https://github.com/afonsojramos/super-calendar
- Homepage: https://super-calendar.afonsojramos.me
- npm.io page: https://npm.io/package/@super-calendar/core

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 2.14.1 (latest) — 2026-10-20
- 2.14.0 — 2026-10-13
- 2.13.0 — 2026-10-09
- 2.12.1 — 2026-10-07
- 2.12.0 — 2026-10-06
- 2.11.1 — 2026-10-06
- 2.11.0 — 2026-09-15
- 2.10.0 — 2026-09-08
- 2.9.1 — 2026-09-05
- 2.9.0 — 2026-08-24
- 2.8.2 — 2026-08-20
- 2.8.1 — 2026-07-30
- 2.8.0 — 2026-07-29
- 2.7.0 — 2026-07-27
- 2.6.0 — 2026-07-20
- … 11 more at https://npm.io/package/@super-calendar/core/versions

## README

# @super-calendar/core

[![npm](https://img.shields.io/npm/v/@super-calendar/core?style=flat-square&color=1F6FEB)](https://www.npmjs.com/package/@super-calendar/core) [![JSR](https://img.shields.io/jsr/v/@super-calendar/core?style=flat-square&label=JSR&color=F7DF1E)](https://jsr.io/@super-calendar/core) [![npmx](https://img.shields.io/badge/npmx-view-8A2BE2?style=flat-square)](https://npmx.dev/package/@super-calendar/core)

The render-agnostic core of [super-calendar](https://github.com/afonsojramos/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`](https://www.npmjs.com/package/@super-calendar/dom) (react-dom) or [`@super-calendar/native`](https://www.npmjs.com/package/@super-calendar/native) (React Native).

## Install

```sh
npm install @super-calendar/core
```

Also on [JSR](https://jsr.io/@super-calendar/core): `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.

```tsx
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`:

```ts
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:

```ts
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.

## Documentation

See the [full documentation](https://super-calendar.afonsojramos.me) and the [API reference](https://super-calendar.afonsojramos.me/reference/api).

## License

MIT

---
_Source: https://npm.io/package/@super-calendar/core · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._