# 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:

```bash
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](https://ui.shadcn.com/docs/installation) 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:

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

### Add components

Add the full calendar:

```bash
npx shadcn add @calendarcn/calendar
```

Or the whole [live demo](/), sidebars and command menu included:

```bash
npx shadcn add @calendarcn/calendar-app
```

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

```bash
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

```tsx title="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

| 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](/docs/components/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](/docs/components/event-details#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](/docs/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](/docs/components/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](/docs/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:

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

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

```bash
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

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

```bash
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](/docs/components/calendar-core#configuration),
> `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.
