RegistryInstall CalendarCN with the shadcn CLI

Components

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, built from this block.Open full screen

CalendarApp is the live demo, whole: the Calendar Sidebar on the left, the Calendar Header over the day, week, month, year and agenda views, the Details Sidebar on the right, the Command Menu, the toasts 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 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 block instead.

Installation

pnpm dlx shadcn add @calendarcn/calendar-app

The install brings every part of the demo, plus Sample Data and the placeholder 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' theme. Wrap your app in the ThemeProvider the block installed, in the root layout:

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:

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.

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.

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:

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.
  • createEvent builds the event a double-click or a drag on empty space starts (see Creating events), onEventCreate, onEventUpdate and onEventSelect report single changes, and onVisibleRangeChange with loading loads events by range: see Loading Events.

.ics files

The command menu's "Import .ics file..." reads a file with parseIcs(), 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() 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:

<CalendarApp
  defaultEvents={events}
  settingsDialog
  onAddCalendarAccount={({ importIcsCalendar }) => importIcsCalendar()}
  onSupport={() => window.open(ISSUES_URL, "_blank")}
  onAbout={() => router.push("/docs")}
/>
  • settingsDialog turns on the 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:

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

WidthCalendar sidebarDetails sidebar
1280px and widerInline, openInline, open
768px to 1279pxInline, openOver the calendar, closed
Under 768pxSheet, closedSheet, 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.

Keyboard shortcuts

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

ActionShortcut
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 shareS

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:

API Reference

CalendarApp takes every CalendarProvider prop (events, view, date, calendars, contacts, rooms, conferencing, configuration and render slots), for DetailedCalendarEvent events, plus these:

PropTypeDefault
headerActions
Shown in the header before the view switcher on wide screens, e.g. the signed-in user's avatar.
React.ReactNode–
sidebarFooterActions
Buttons in the calendar sidebar's footer, before the theme toggle.
React.ReactNode–
onEventsImport
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.
(events: DetailedCalendarEvent[]) => void–
exportFileName
Name of the file the command menu's .ics export downloads.
string"calendar.ics"
exportCalendarName
Calendar name written into the exported .ics. Google Calendar and Apple Calendar show it.
string–
settingsDialog
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.
booleanfalse
onOpenSettings
Called on ⌘, (Ctrl+, elsewhere) and "Go to settings", for settings of your own. Without it or settingsDialog, the key is left to the browser.
() => void–
onAddCalendarAccount
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.
(helpers: { importIcsCalendar: () => void }) => void–
onSupport
Adds "Support & feedback" to the command menu, e.g. to open your issue tracker.
() => void–
onAbout
Adds "About CalendarCN" to the command menu, e.g. to open your docs.
() => void–
onCreateSchedulingLink
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).
(request: SchedulingLinkRequest) => void–
showComingSoon
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.
booleanfalse
scrollToHour
Hour the time grid scrolls to when it mounts, e.g. 8.5 for 8:30 AM.
number8
shortcuts
Whether the keyboard shortcuts are on: the calendar's single keys and the app's ⌘K, ⌘/, /, ⇧M, . and ?. They listen on window.
booleantrue
className
Classes for the root, which fills the viewport (h-screen).
string–
children
Rendered inside the provider, after the app. Useful for your own dialogs that read useCalendar().
React.ReactNode–

On this page