# Introduction

A calendar for React inspired by Notion Calendar. Built on shadcn/ui, installed with the shadcn CLI, and yours to edit.

CalendarCN is an open-source calendar for React. It brings the feel of Notion Calendar (fast keyboard navigation, drag to move and resize, a quiet interface) to any app that uses [shadcn/ui](https://ui.shadcn.com) and Tailwind CSS. Pick the question that sounds like you to jump to its answer and the pages that go deeper.

- [How do I install it?](https://calendarcn.xyz/docs#install)
- [How do I show my own events?](https://calendarcn.xyz/docs#your-events)
- [How do I customize it?](https://calendarcn.xyz/docs#customize)
- [How do I get updates?](https://calendarcn.xyz/docs#updates)
- [What's coming next?](https://calendarcn.xyz/docs#whats-next)

**Not sure where to start?** Try the live demo: drag events to move them, drag their edges to resize, and switch between day, week, month, year and agenda. The source is on GitHub under the MIT license. [Open the live demo](https://calendarcn.xyz/) or [the repository](https://github.com/vmnog/calendarcn).

## What's included

- **Views**: day, week, any number of days from 2 to 9, month, the year as twelve month grids, and an agenda that lists the next 30 days.
- **Direct manipulation**: drag events to move them, drag their edges to resize, double-click or drag on empty space to create one.
- **Real calendar data**: overlapping events side by side, multi-day and all-day events, a current-time indicator.
- **Event details**: a side panel or popover with inline editing.
- **Import and export**: read and write .ics files from Google Calendar, Apple Calendar and Outlook. See [Import and Export](/docs/import-export).
- **Keyboard first**: shortcuts for every view, and the live demo's [command menu](/docs/components/command-menu). See [Keyboard shortcuts](/docs/keyboard-shortcuts).
- **Theming**: light and dark mode with the shadcn/ui CSS variables.

## How do I install it?

Like shadcn/ui, CalendarCN isn't an npm dependency. The shadcn CLI copies the source into your project, so you can read it, restyle it and change how it behaves.

The [Installation](/docs/installation) guide sets up shadcn/ui and adds the `@calendarcn` registry to your `components.json`. Then add the full calendar with one command:

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

Or add only the pieces you need. Each one pulls in the ones it builds on.

- [Calendar](/docs/components/calendar): The full calendar: a toolbar and view switcher over the day, week, month, year and agenda views.
- [Calendar App](/docs/components/calendar-app): The whole live demo in one install: both sidebars, the header, every view, the command menu and .ics files.
- [Calendar Core](/docs/components/calendar-core): `CalendarProvider` and `useCalendar()`, the state every view shares.
- [Time Grid](/docs/components/time-grid): The scrollable hour grid behind the day and week views.
- [Day View](/docs/components/day-view): A single day on the time grid.
- [Week View](/docs/components/week-view): A week, or any number of days, on the time grid.
- [Month View](/docs/components/month-view): A month at a glance.
- [Agenda View](/docs/components/agenda-view): The next 30 days' events as a scrolling list, grouped by day.
- [Year View](/docs/components/year-view): Twelve months at a glance, with the days that have events marked.
- [Event Details](/docs/components/event-details): Event chips, and the panel, popover and menu for viewing and editing an event.

## How do I show my own events?

Pass them in. An event needs an `id`, a `title`, a `start` and an `end`. Give the calendar `defaultEvents` and it owns them, or pass `events` with `onEventsChange` and your app does: every drag, resize, create and edit comes back as the full next list.

```tsx
const [events, setEvents] = React.useState(initialEvents);

<Calendar events={events} onEventsChange={setEvents} />;
```

Already keep them in Google Calendar, Apple Calendar or Outlook? `parseIcs()` turns an exported .ics file into events, and `toIcs()` writes them back out.

- [Controlled or uncontrolled](/docs/components/calendar-core#controlled-or-uncontrolled): Who owns the events, and `onEventCreate`, `onEventUpdate` and `onEventSelect` for saving one change at a time.
- [Loading Events](/docs/loading-events): Fetch events for the dates on screen as people navigate, with a loading bar while they arrive.
- [Import and Export](/docs/import-export): Read and write .ics files, plus a recipe that syncs with Google Calendar.
- [Event fields](/docs/components/calendar-core#calendarevent): The four required fields, plus `isAllDay` for the all-day row and `color` for one of the seven event colors.
- [Typed events](/docs/components/calendar-core#typed-events): Extend `CalendarEvent` with your own fields, and every callback and renderer gets your type back.

## How do I customize it?

The CLI copies the source into your project, so you can change the toolbar or the layout right in `components/calendar.tsx`. Before you edit it, check the props: many changes are one prop away.

- [Settings](/docs/components/calendar-core#configuration): A 24-hour clock, a date-fns locale, the first day of the week, the visible hours and the snap step are plain props.
- [Event content](/docs/components/calendar-core#custom-event-content): `renderEventContent` draws inside each event. `renderEventDetails` replaces the details popover.
- [Theming](/docs/components/calendar#theming): Your shadcn/ui theme, plus `--event-{color}` tokens for the seven event colors in light and dark mode.
- [Build your own](/docs/components/calendar#build-your-own): Compose your own header with `useCalendar()` around any view.

The single-key shortcuts can be turned off with `shortcuts={false}` or changed: see [Keyboard shortcuts](/docs/keyboard-shortcuts#use-them-in-your-own-calendar).

## How do I get updates?

There's no package version to bump. Fixes and improvements are live in the registry as soon as they merge, and running `add` again with `--overwrite` brings them into your project. Preview the changes with `--dry-run` first.

- [Updating](/docs/installation#updating): Preview an update, apply it, and put your own edits back.
- [Changelog](/docs/changelog): What changed in each item, newest first, with breaking changes called out.

## What's coming next?

CalendarCN is built in the open, and plans change as people use it. The Notion-style event details panel shipped most recently. Up next is listing CalendarCN in the shadcn/ui registry directory, next to the other community registries. Later plans include a year view and a resource view, and virtualized rendering for thousands of events.

- [Roadmap](/docs/roadmap): Everything that's planned, roughly in priority order, and what shipped recently.
- [Suggest something](https://github.com/vmnog/calendarcn/issues/new): Missing something you need? Open an issue on GitHub and describe what you're building.

## Built with

[Next.js](https://nextjs.org), [React](https://react.dev), [Tailwind CSS](https://tailwindcss.com), [shadcn/ui](https://ui.shadcn.com) and [date-fns](https://date-fns.org). The source is on [GitHub](https://github.com/vmnog/calendarcn) under the MIT license.
