# Calendar App

The live demo as one block, with both sidebars, the header, every view, the command menu, theme switching and .ics files.

[The live demo](https://calendarcn.xyz/), built from this block.

`CalendarApp` is the [live demo](/), whole: the [Calendar Sidebar](/docs/components/calendar-sidebar) on the left, the [Calendar Header](/docs/components/calendar-header) over the day, week, month, year and agenda views, the [Details Sidebar](/docs/components/details-sidebar) on the right, the [Command Menu](/docs/components/command-menu), the [toasts](/docs/components/calendar-toaster) after a delete, cut or copy, theme switching, .ics import and export, and the keyboard shortcuts. The live demo renders this block, so what you install is what you see there.

It takes every [`CalendarProvider`](/docs/components/calendar-core#calendarprovider) prop, so your events, calendars, contacts, rooms and conferencing services go in as props. For a smaller calendar to put inside a page of yours, use the [Calendar](/docs/components/calendar) block instead.

## Installation

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

Or install it by hand:

1. Install the items it builds on: `@calendarcn/calendar-core`, `@calendarcn/time-grid`, `@calendarcn/month-view`, `@calendarcn/agenda-view`, `@calendarcn/year-view`, `@calendarcn/calendar-header`, `@calendarcn/command-menu`, `@calendarcn/people-picker`, `@calendarcn/calendar-toaster`, `@calendarcn/calendar-settings`, `@calendarcn/calendar-sidebar`, `@calendarcn/details-sidebar`, `@calendarcn/theme-toggle`, `@calendarcn/ics`, `@calendarcn/sample-data`, `@calendarcn/conference-providers`
2. Install the dependencies: `npm install next-themes`
3. Add the shadcn/ui components it uses: `npx shadcn add sidebar`
4. Copy these files into your project, keeping the paths under your components, hooks and lib folders:
   - [`components/calendar-app.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/calendar-app.tsx)

The install brings every part of the demo, plus [Sample Data](/docs/sample-data) and the placeholder [conference providers](/docs/components/event-details#conference-providers), so the page below reproduces the live demo. Delete `lib/mock-events.ts`, `lib/sample-events.ts` and `lib/conference-providers.ts` once you pass your own data.

## Usage

### Add the theme provider

The theme toggle, `⇧M` and the command menu's theme command switch [next-themes](https://github.com/pacocoursey/next-themes)' theme. Wrap your app in the `ThemeProvider` the block installed, in the root layout:

```tsx title="app/layout.tsx"
import { ThemeProvider } from "@/components/theme-provider";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider
          attribute="class"
          defaultTheme="system"
          enableSystem
          disableTransitionOnChange
        >
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}
```

### Render the app

`CalendarApp` fills the viewport, so give it a page of its own:

```tsx title="app/calendar/page.tsx"
"use client";

import * as React from "react";

import { CalendarApp } from "@/components/calendar-app";
import { DEMO_CONFERENCE_PROVIDERS } from "@/lib/conference-providers";
import {
  DEMO_CALENDARS,
  DEMO_CONTACTS,
  DEMO_LOCATION_SUGGESTIONS,
  DEMO_ROOMS,
  generateMockEvents,
} from "@/lib/mock-events";

export default function CalendarPage() {
  // The app reads its initial events once, so create them once
  const [initialEvents] = React.useState(() => generateMockEvents());

  return (
    <CalendarApp
      defaultEvents={initialEvents}
      defaultViewSettings={{ showWeekNumbers: true }}
      calendars={DEMO_CALENDARS}
      contacts={DEMO_CONTACTS}
      rooms={DEMO_ROOMS}
      conferenceProviders={DEMO_CONFERENCE_PROVIDERS}
      locationSuggestions={DEMO_LOCATION_SUGGESTIONS}
      showComingSoon
    />
  );
}
```

That's the live demo. Its own page adds an avatar to the header (`headerActions`), docs and GitHub buttons to the sidebar's footer (`sidebarFooterActions`), logos to the conferencing services, and a random color for each event you create (`createEvent`): see [`src/app/page.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/app/page.tsx).

The calendar renders in the browser only, since "today" and the time zone belong to the viewer. With Next.js Cache Components, create date-based events in an effect or load them from your API: see [Installation](/docs/installation).

## Your own data

The app takes the same props as `CalendarProvider`, for `DetailedCalendarEvent` events: the fields the details sidebar edits, from participants to reminders. Leave the events to the app with `defaultEvents`, or keep them in your state with `events` and `onEventsChange`:

```tsx
const [events, setEvents] = React.useState<DetailedCalendarEvent[]>([]);

<CalendarApp
  events={events}
  onEventsChange={setEvents}
  calendars={calendars}
  contacts={contacts}
  rooms={rooms}
  conferenceProviders={conferenceProviders}
  locationSuggestions={locationSuggestions}
  onEventsImport={(imported) => saveEvents(imported)}
/>;
```

- `calendars` fill the sidebar's calendar list and the details' calendar picker; an event without its own `color` takes its calendar's.
- The eye beside a calendar in the sidebar hides its events: they leave every view and the event search, and come back when it's shown again. An event created on a hidden calendar, or moved to one, shows that calendar again.
- `contacts` and `rooms` are who and what the details' participants field invites. `conferenceProviders` fill its Conferencing menu, and `locationSuggestions` its location field.
- `contacts` are also who you can meet with: the sidebar's "Meet with...", `F` and `P` add them, and `contactEvents` holds their events, by email, to draw beside yours. See [Meeting with people](/docs/components/calendar-core#meeting-with-people).
- `createEvent` builds the event a double-click or a drag on empty space starts (see [Creating events](/docs/components/calendar-core#creating-events)), `onEventCreate`, `onEventUpdate` and `onEventSelect` report single changes, and `onVisibleRangeChange` with `loading` loads events by range: see [Loading Events](/docs/loading-events).

### .ics files

The command menu's "Import .ics file..." reads a file with [`parseIcs()`](/docs/import-export), adds its events and goes to the first one. An event whose id is already there is replaced, so importing the same file again updates it. Controlled or not, the new list comes back through `onEventsChange`, and `onEventsImport` gets only the imported events, to save them.

"Export .ics file" writes every event, those of hidden calendars included, with [`toIcs()`](/docs/import-export#export-events) and downloads it as `exportFileName`, with `exportCalendarName` as the calendar's name.

### Settings and accounts

The account and app controls show only when you turn them on, as the live demo does:

```tsx
<CalendarApp
  defaultEvents={events}
  settingsDialog
  onAddCalendarAccount={({ importIcsCalendar }) => importIcsCalendar()}
  onSupport={() => window.open(ISSUES_URL, "_blank")}
  onAbout={() => router.push("/docs")}
/>
```

- `settingsDialog` turns on the [Calendar Settings](/docs/components/calendar-settings) dialog: `⌘,` and "Go to settings" open it, and "Manage calendar accounts" opens it on the calendars. Its theme setting switches next-themes' theme, and its time format the clock every view shows. For settings of your own, pass `onOpenSettings` instead.
- `onAddCalendarAccount` adds "Add calendar account" to the sidebar, the command menu and the settings. Connect an account your way, or call `importIcsCalendar()`, which opens a file picker and adds the file's events as a calendar named after the file, then shows the first one. The same file again updates that calendar.
- `onSupport` and `onAbout` add "Support & feedback" and "About CalendarCN" to the command menu.

### Your own buttons

Put your account menu in the header with `headerActions`, and your own buttons in the sidebar's footer, before the theme toggle, with `sidebarFooterActions`:

```tsx
<CalendarApp
  headerActions={
    <Avatar className="size-7">
      <AvatarImage src={user.image} alt={user.name} />
      <AvatarFallback>{user.initials}</AvatarFallback>
    </Avatar>
  }
  sidebarFooterActions={
    <Button variant="ghost" size="icon" className="size-7" asChild>
      <a href="/help">
        <CircleHelpIcon />
        <span className="sr-only">Help</span>
      </a>
    </Button>
  }
/>
```

`headerActions` shows on wide headers only, before the view switcher. Beyond these, the CLI copied the source into `components/calendar-app.tsx`: change the layout there.

## Layout

The app fills the viewport and follows its width:

| Width            | Calendar sidebar | Details sidebar                                       |
| ---------------- | ---------------- | ----------------------------------------------------- |
| 1280px and wider | Inline, open     | Inline, open                                          |
| 768px to 1279px  | Inline, open     | Over the calendar, closed                             |
| Under 768px      | Sheet, closed    | Sheet, closed; selecting an event opens it on details |

From 768px up, while the details sidebar is closed, a selected event shows its details in a popover, with a button that moves them into the sidebar. The sidebars' colors are their own tokens: see [Colors](/docs/components/calendar-sidebar#colors).

## Keyboard shortcuts

`CalendarApp` turns on the calendar's single-key [shortcuts](/docs/keyboard-shortcuts) (`T`, `J`/`K`, `D`, `W`, `M`, `Y`, `A`, `C`…) and the app's own:

| Action                                              | Shortcut |
| --------------------------------------------------- | -------- |
| Command menu                                        | `⌘K`     |
| Toggle the calendar sidebar                         | `⌘/`     |
| Toggle the details sidebar                          | `/`     |
| Cycle theme (system, light, dark)                   | `⇧M`     |
| Settings, with `settingsDialog` or `onOpenSettings` | `⌘,`     |
| Go to date                                          | `.`     |
| All keyboard shortcuts, in the details sidebar      | `?`     |
| Meet with...                                        | `F`     |
| Show teammate calendar...                           | `P`     |
| Mark open times to share                            | `S`     |

They listen on the whole page. Pass `shortcuts={false}` to turn them all off.

Press `.` to open the command menu on Go to date: type a date ("tomorrow", "next friday", "dec 25", "in 2 weeks") and press `Enter` to show it in the current view. Press `?` to see every shortcut the app handles in the details sidebar, grouped as Notion Calendar groups them, with a field to find one by name or key. The command menu's "Search events" opens the details sidebar's event search with the field focused, and text typed in the menu offers "Search events for “…”".

## Parts

`CalendarApp` is a short file that puts these items together. To build a layout of your own, install the ones you need:

- [Calendar Core](/docs/components/calendar-core): `CalendarProvider`, `useCalendar()` and `useCalendarShortcuts()`.
- [Calendar Sidebar](/docs/components/calendar-sidebar): the left sidebar, with the [Mini Calendar](/docs/components/mini-calendar), the [Calendar List](/docs/components/calendar-list) and the [Theme Toggle](/docs/components/theme-toggle).
- [Calendar Header](/docs/components/calendar-header): the toolbar, with the view switcher and the panel toggles.
- [Time Grid](/docs/components/time-grid), [Month View](/docs/components/month-view), [Year View](/docs/components/year-view) and [Agenda View](/docs/components/agenda-view): the views.
- [Details Sidebar](/docs/components/details-sidebar): the right sidebar, with the [Event Details](/docs/components/event-details).
- [Command Menu](/docs/components/command-menu): the `⌘K` menu.
- [Calendar Settings](/docs/components/calendar-settings): the settings dialog.
- [People Picker](/docs/components/people-picker): the `F` and `P` dialog, to meet with someone or show a teammate's calendar.
- [Calendar Toaster](/docs/components/calendar-toaster): the toasts after a delete, cut or copy, with Undo.
- [Scheduling](/docs/components/scheduling): marking open times and copying them as text, and scheduling links through `onCreateSchedulingLink`.
- [Sidebar Overlay](/docs/components/sidebar-overlay): both sidebars as sheets on narrow screens, and their colors.
- [Import and Export](/docs/import-export): `parseIcs()` and `toIcs()`.
- [Sample Data](/docs/sample-data) and the [conference providers](/docs/components/event-details#conference-providers): the demo's data.

## API Reference

`CalendarApp` takes every [`CalendarProvider` prop](/docs/components/calendar-core#calendarprovider) (events, view, date, calendars, contacts, rooms, conferencing, configuration and render slots), for `DetailedCalendarEvent` events, plus these:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `headerActions` | `React.ReactNode` | – | Shown in the header before the view switcher on wide screens, e.g. the signed-in user's avatar. |
| `sidebarFooterActions` | `React.ReactNode` | – | Buttons in the calendar sidebar's footer, before the theme toggle. |
| `onEventsImport` | `(events: DetailedCalendarEvent[]) => void` | – | Called with the events of an .ics file imported from the command menu, after they're added. An event whose id is already there is replaced. |
| `exportFileName` | `string` | `"calendar.ics"` | Name of the file the command menu's .ics export downloads. |
| `exportCalendarName` | `string` | – | Calendar name written into the exported .ics. Google Calendar and Apple Calendar show it. |
| `settingsDialog` | `boolean` | `false` | Turns on the built-in [Calendar Settings](/docs/components/calendar-settings) dialog: ⌘, (Ctrl+, elsewhere) and "Go to settings" open it, and "Manage calendar accounts" opens it on the calendars. It wins over `onOpenSettings`. |
| `onOpenSettings` | `() => void` | – | Called on ⌘, (Ctrl+, elsewhere) and "Go to settings", for settings of your own. Without it or `settingsDialog`, the key is left to the browser. |
| `onAddCalendarAccount` | `(helpers: { importIcsCalendar: () => void }) => void` | – | Adds "Add calendar account" to the sidebar, the command menu and the settings. `importIcsCalendar()` adds an .ics file as a new calendar, as the live demo does. |
| `onSupport` | `() => void` | – | Adds "Support & feedback" to the command menu, e.g. to open your issue tracker. |
| `onAbout` | `() => void` | – | Adds "About CalendarCN" to the command menu, e.g. to open your docs. |
| `onCreateSchedulingLink` | `(request: SchedulingLinkRequest) => void` | – | Creates a scheduling link (a booking page) in your app. With it, the sidebar's Scheduling row and the command menu offer recurring and one-off links. See [Scheduling links](/docs/components/scheduling#scheduling-links). |
| `showComingSoon` | `boolean` | `false` | Also lists the Notion Calendar commands CalendarCN doesn't have yet in the command menu, disabled with a "Soon" badge, as the live demo does. |
| `scrollToHour` | `number` | `8` | Hour the time grid scrolls to when it mounts, e.g. `8.5` for 8:30 AM. |
| `shortcuts` | `boolean` | `true` | Whether the keyboard shortcuts are on: the calendar's single keys and the app's ⌘K, ⌘/, /, ⇧M, . and ?. They listen on `window`. |
| `className` | `string` | – | Classes for the root, which fills the viewport (`h-screen`). |
| `children` | `React.ReactNode` | – | Rendered inside the provider, after the app. Useful for your own dialogs that read `useCalendar()`. |
