RegistryInstall CalendarCN with the shadcn CLI

Getting Started

Installation

Add CalendarCN to your project with the shadcn CLI.

Set up shadcn/ui

CalendarCN builds on shadcn/ui and Tailwind CSS 4. It works with both component libraries shadcn/ui offers, Base UI and Radix. In a new project, pick either one when you set up shadcn/ui:

npx shadcn init -b base

Use -b radix for Radix instead.

Projects already on a Radix style (new-york, radix-nova and the other radix-* presets) or a Base UI style (base-nova and the other base-* presets) are ready. See the shadcn/ui installation guide for frameworks other than Next.js.

Add the registry

Add the @calendarcn namespace to registries in your components.json. The registry is served from this site:

components.json
{
  "registries": {
    "@calendarcn": "https://calendarcn.xyz/r/{name}.json"
  }
}

Add components

Add the full calendar:

npx shadcn add @calendarcn/calendar

Or the whole live demo, sidebars and command menu included:

npx shadcn add @calendarcn/calendar-app

Or only the pieces you need, like the week view:

npx shadcn add @calendarcn/week-view

The CLI copies the files into your components, hooks and lib folders, installs their npm dependencies and the shadcn/ui components they use, and adds the calendar's color tokens to your CSS file.

Render it

app/calendar/page.tsx
"use client";

import * as React from "react";

import { Calendar } from "@/components/calendar";
import type { CalendarEvent } from "@/components/calendar-types";

export default function CalendarPage() {
  const [events, setEvents] = React.useState<CalendarEvent[]>([]);

  React.useEffect(() => {
    // Load your events here, e.g. from your API
    setEvents([
      {
        id: "1",
        title: "Team standup",
        start: new Date(2026, 10, 2, 9, 0),
        end: new Date(2026, 10, 2, 9, 30),
        color: "blue",
      },
    ]);
  }, []);

  return (
    <div className="h-screen">
      <Calendar events={events} onEventsChange={setEvents} />
    </div>
  );
}

The calendar fills its parent's height, so give the parent one. It renders in the browser only, since "today" and the time zone belong to the viewer.

Next.js Cache Components

With cacheComponents on (the default for new Next.js 16 apps), new Date() can't run while a page prerenders. Create date-based events in an effect or an event handler, or load them from your API, as above.

Registry items

ItemWhat it adds
@calendarcn/calendarThe full calendar: toolbar, view switcher and keyboard shortcuts over the day, week, month, year and agenda views.
@calendarcn/calendar-appThe live demo as one block: both sidebars, the header, the views, the ⌘K menu, theme switching, .ics import and export, and the shortcuts. Brings the sample data. See Calendar App.
@calendarcn/calendar-coreTypes, event layout math, CalendarProvider, useCalendar(), useCalendarShortcuts() and the color tokens. Repeat rules in @/lib/recurrence (parseRecurrence, formatRRule, describeRecurrenceRule, expandRecurringEvents, findSeriesOccurrence) and time zones in @/lib/time-zones (getEventTimeZone, changeTimeZoneKeepingWallClock).
@calendarcn/time-gridThe hour grid behind the day and week views, with drag, resize and create.
@calendarcn/day-viewOne day on the time grid.
@calendarcn/week-viewA week, or any number of days, on the time grid.
@calendarcn/month-viewThe month grid, with drag and resize.
@calendarcn/agenda-viewThe coming days' events as a scrolling list, grouped by day.
@calendarcn/year-viewThe year as twelve month grids, with today and the days that have events marked.
@calendarcn/event-detailsEvent chips, the detail panel, the details popover and the right-click menu.
@calendarcn/icsparseIcs() and toIcs(): read and write .ics files from Google Calendar, Apple Calendar and Outlook.
@calendarcn/conference-providersPlaceholder Google Meet, Zoom and Microsoft Teams for the details' Conferencing row, to pass to conferenceProviders. See Conference providers.
@calendarcn/sample-dataThe live demo's events, calendars, contacts, rooms and places, and the docs examples' week of events. See Sample Data.
@calendarcn/calendar-headerThe live demo's header: month and year with the period on screen, view switcher, today, previous/next and panel toggles. Also its parts, for a header of your own.
@calendarcn/command-menuThe live demo's ⌘K menu: today, previous/next and the views, plus your app's panel, theme and .ics commands.
@calendarcn/calendar-settingsNotion Calendar's settings dialog: the calendar view, time format and theme, and each account's calendars.
@calendarcn/people-pickerThe dialog F and P open: search your contacts to meet with someone or show a teammate's calendar. See People Picker.
@calendarcn/calendar-sidebarThe demo's left sidebar: mini calendar, scheduling, "Meet with...", calendar list and theme toggle, inline or as an overlay.
@calendarcn/mini-calendarThe sidebar's month picker, with week numbers and the visible days highlighted.
@calendarcn/calendar-listThe calendars grouped by account, each with a show and hide button.
@calendarcn/theme-toggleA button that cycles system, light and dark, with the next-themes provider.
@calendarcn/details-sidebarThe demo's right context panel: the selected event's details, event search and useful shortcuts.
@calendarcn/sidebar-overlayA sidebar as a modal sheet on narrow screens, and the sidebars' color tokens.

Each item pulls in the ones it builds on, so calendar installs all of them except day-view and week-view, which it doesn't need (it renders the time grid directly), ics, which you add to import or export .ics files, conference-providers and sample-data, which you add to try the calendar with the live demo's services and data, command-menu, people-picker, and the sidebars, which you add around it. calendar-sidebar installs the mini calendar, calendar list, theme toggle and sidebar overlay. calendar-app installs everything the live demo uses, ics, conference-providers, sample-data, command-menu, people-picker, calendar-settings and both sidebars included.

Updating

There's no package to upgrade. The registry at calendarcn.xyz/r serves the latest main, so every fix and improvement is live there as soon as its pull request merges, without waiting for a release. The Changelog lists what changed in each item and calls out breaking changes.

To update, run add again for the items you installed. Each item updates the items it builds on, so @calendarcn/calendar updates all of them.

Preview the changes

--dry-run writes nothing. It lists every file the update would create, the files that changed and would be overwritten, and the identical files it skips, plus any new npm dependencies and CSS variables:

npx shadcn@latest add @calendarcn/calendar --dry-run

To see what changed in one of the files marked overwrite, pass its path as the list shows it:

npx shadcn@latest add @calendarcn/calendar --diff components/calendar.tsx

Without a path, --diff only shows the first five files.

Commit, then overwrite

Commit your work first, so the update lands as a diff you can review and undo. Then run add with --overwrite:

npx shadcn@latest add @calendarcn/calendar --overwrite

It replaces the files that changed, creates the new ones, and installs any new npm dependencies and shadcn/ui components. Without --overwrite, the CLI stops to ask about each file that changed.

Review and reapply your edits

git diff

Your own edits to the copied files show up as removed lines, since the update replaced them. Put them back by hand. When a hunk holds only your edit, git checkout -p restores it:

git checkout -p -- components/calendar.tsx

Then type-check and try your app before you commit the update.

Customize with props to keep updates clean

Every copied file you edit is one you merge by hand on each update. Reach for props first: the settings, renderEventContent and renderEventDetails, or your own components built on useCalendar(). add only writes the registry's files and the color tokens in your CSS file, so code in your own files is never overwritten.

On this page