Installation

Hapio Calendar comes in two parts: npm packages with the logic (no markup, no CSS), and registry items with the markup and the Tailwind classes, which the shadcn CLI copies into your app. Most apps install the registry block and get the packages with it.

RequirementsCopy Anchor Link

• React and React DOM 19.2 or later.
• A shadcn/ui app with Tailwind CSS 4: either base works, Radix (radix-nova) or Base UI (base-nova), because the registry files import only your own shadcn components (@/components/ui/button and the like), never a primitive library directly.
• TypeScript 5.9 or later, if you use TypeScript (the types are checked against 5.9, 6.0 and 7.0).
• For server rendering, Node 22.12 or later.

1. Add the registry namespaceCopy Anchor Link

The registry items name each other @hapio/<item>. Add the namespace to your app's components.json:

{
  "registries": {
    "@hapio": "https://calendar.hapio.io/r/{style}/{name}.json"
  }
}

{style} lets the registry serve a per-base file where one is ever needed; today every item is the same for both bases. https://calendar.hapio.io/r/{name}.json serves the base-agnostic files only.

2. Add the calendarCopy Anchor Link

npx shadcn@latest add @hapio/hapio-calendar

This copies the hapio-calendar block into components/hapio-calendar/ together with the items it is built from, adds the shadcn components they use (button, popover, scroll-area) and installs the npm dependencies @hapio/calendar-react, cn and temporal-polyfill. The calendar-theme item adds the calendar's CSS variables and styles to your global CSS.

3. Load the Temporal polyfillCopy Anchor Link

The calendar's dates are Temporal objects, which not every browser and runtime has yet. Load temporal-polyfill once per app, before the calendar renders; it leaves a native Temporal alone.

// instrumentation.ts: runs once when the Next.js server starts, before any page renders.
export async function register(): Promise<void> {
  // Node before 26 has no Temporal; the polyfill leaves a native one alone.
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('temporal-polyfill/global')
  }
}

4. Give it a height and a time zoneCopy Anchor Link

<HapioCalendar events={events} timeZone="Europe/Stockholm" className="h-[36rem]" />

The calendar fills the height of its root (toolbar included) and scrolls inside. For a complete server render, give it a date as well: with an IANA timeZone and a date (defaultDate or date) or now, the server renders the whole calendar, events included (SSR and RSC). Continue with your first calendar.

Interactions are separate itemsCopy Anchor Link

The block on its own is read-only, and a read-only page ships none of the interaction code. Add the items you need and wrap the calendar in their component:

calendar-editing brings calendar-event-actions (the actions menu and the "Change time…" form) and calendar-recurrence-scope-dialog (the "which events?" dialog of recurring events).

The registry itemsCopy Anchor Link

Every item can be added on its own; its dependencies come with it. Each copied file starts with a stamp, // @hapio/calendar registry X.Y.Z · contract 1: the hooks warn in development when the files implement another contract than the installed @hapio/calendar-react. See Upgrading.

The npm packagesCopy Anchor Link

The four @hapio packages are released together under one version: install the same version of each. They are ES modules only, with no CSS and no side effects, and every hook file carries its own 'use client', so the packages work in React Server Components where the SSR guide says.

Without the registryCopy Anchor Link

The hooks work with markup of your own, in any styling system: npm install @hapio/calendar-react temporal-polyfill, then follow Customization and check your markup with runConformance.