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 baseUse -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:
{
"registries": {
"@calendarcn": "https://calendarcn.xyz/r/{name}.json"
}
}Add components
Add the full calendar:
npx shadcn add @calendarcn/calendarOr the whole live demo, sidebars and command menu included:
npx shadcn add @calendarcn/calendar-appOr only the pieces you need, like the week view:
npx shadcn add @calendarcn/week-viewThe 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
"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
| Item | What it adds |
|---|---|
@calendarcn/calendar | The full calendar: toolbar, view switcher and keyboard shortcuts over the day, week, month, year and agenda views. |
@calendarcn/calendar-app | The 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-core | Types, 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-grid | The hour grid behind the day and week views, with drag, resize and create. |
@calendarcn/day-view | One day on the time grid. |
@calendarcn/week-view | A week, or any number of days, on the time grid. |
@calendarcn/month-view | The month grid, with drag and resize. |
@calendarcn/agenda-view | The coming days' events as a scrolling list, grouped by day. |
@calendarcn/year-view | The year as twelve month grids, with today and the days that have events marked. |
@calendarcn/event-details | Event chips, the detail panel, the details popover and the right-click menu. |
@calendarcn/ics | parseIcs() and toIcs(): read and write .ics files from Google Calendar, Apple Calendar and Outlook. |
@calendarcn/conference-providers | Placeholder Google Meet, Zoom and Microsoft Teams for the details' Conferencing row, to pass to conferenceProviders. See Conference providers. |
@calendarcn/sample-data | The live demo's events, calendars, contacts, rooms and places, and the docs examples' week of events. See Sample Data. |
@calendarcn/calendar-header | The 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-menu | The live demo's ⌘K menu: today, previous/next and the views, plus your app's panel, theme and .ics commands. |
@calendarcn/calendar-settings | Notion Calendar's settings dialog: the calendar view, time format and theme, and each account's calendars. |
@calendarcn/people-picker | The dialog F and P open: search your contacts to meet with someone or show a teammate's calendar. See People Picker. |
@calendarcn/calendar-sidebar | The demo's left sidebar: mini calendar, scheduling, "Meet with...", calendar list and theme toggle, inline or as an overlay. |
@calendarcn/mini-calendar | The sidebar's month picker, with week numbers and the visible days highlighted. |
@calendarcn/calendar-list | The calendars grouped by account, each with a show and hide button. |
@calendarcn/theme-toggle | A button that cycles system, light and dark, with the next-themes provider. |
@calendarcn/details-sidebar | The demo's right context panel: the selected event's details, event search and useful shortcuts. |
@calendarcn/sidebar-overlay | A 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-runTo 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.tsxWithout 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 --overwriteIt 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 diffYour 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.tsxThen 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.