Components
Calendar App
The live demo as one block, with both sidebars, the header, every view, the command menu, theme switching and .ics files.
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-appThe 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:
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:
"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)}
/>;calendarsfill the sidebar's calendar list and the details' calendar picker; an event without its owncolortakes 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.
contactsandroomsare who and what the details' participants field invites.conferenceProvidersfill its Conferencing menu, andlocationSuggestionsits location field.contactsare also who you can meet with: the sidebar's "Meet with...", F and P add them, andcontactEventsholds their events, by email, to draw beside yours. See Meeting with people.createEventbuilds the event a double-click or a drag on empty space starts (see Creating events),onEventCreate,onEventUpdateandonEventSelectreport single changes, andonVisibleRangeChangewithloadingloads 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")}
/>settingsDialogturns 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, passonOpenSettingsinstead.onAddCalendarAccountadds "Add calendar account" to the sidebar, the command menu and the settings. Connect an account your way, or callimportIcsCalendar(), 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.onSupportandonAboutadd "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:
| 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.
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:
| 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:
CalendarProvider,useCalendar()anduseCalendarShortcuts(). - Calendar Sidebar: the left sidebar, with the Mini Calendar, the Calendar List and the Theme Toggle.
- Calendar Header: the toolbar, with the view switcher and the panel toggles.
- Time Grid, Month View, Year View and Agenda View: the views.
- Details Sidebar: the right sidebar, with the Event Details.
- Command Menu: the ⌘K menu.
- Calendar Settings: the settings dialog.
- People Picker: the F and P dialog, to meet with someone or show a teammate's calendar.
- Calendar Toaster: the toasts after a delete, cut or copy, with Undo.
- Scheduling: marking open times and copying them as text, and scheduling links through
onCreateSchedulingLink. - Sidebar Overlay: both sidebars as sheets on narrow screens, and their colors.
- Import and Export:
parseIcs()andtoIcs(). - Sample Data and the conference providers: the demo's data.
API Reference
CalendarApp takes every CalendarProvider prop (events, view, date, calendars, contacts, rooms, conferencing, configuration and render slots), for DetailedCalendarEvent events, plus these:
| Prop | Type | Default |
|---|---|---|
headerActionsShown in the header before the view switcher on wide screens, e.g. the signed-in user's avatar. | React.ReactNode | – |
sidebarFooterActionsButtons in the calendar sidebar's footer, before the theme toggle. | React.ReactNode | – |
onEventsImportCalled 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 | – |
exportFileNameName of the file the command menu's .ics export downloads. | string | "calendar.ics" |
exportCalendarNameCalendar name written into the exported .ics. Google Calendar and Apple Calendar show it. | string | – |
settingsDialogTurns 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. | boolean | false |
onOpenSettingsCalled on ⌘, (Ctrl+, elsewhere) and "Go to settings", for settings of your own. Without it or settingsDialog, the key is left to the browser. | () => void | – |
onAddCalendarAccountAdds "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 | – |
onSupportAdds "Support & feedback" to the command menu, e.g. to open your issue tracker. | () => void | – |
onAboutAdds "About CalendarCN" to the command menu, e.g. to open your docs. | () => void | – |
onCreateSchedulingLinkCreates 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 | – |
showComingSoonAlso lists the Notion Calendar commands CalendarCN doesn't have yet in the command menu, disabled with a "Soon" badge, as the live demo does. | boolean | false |
scrollToHourHour the time grid scrolls to when it mounts, e.g. 8.5 for 8:30 AM. | number | 8 |
shortcutsWhether the keyboard shortcuts are on: the calendar's single keys and the app's ⌘K, ⌘/, /, ⇧M, . and ?. They listen on window. | boolean | true |
classNameClasses for the root, which fills the viewport ( h-screen). | string | – |
childrenRendered inside the provider, after the app. Useful for your own dialogs that read useCalendar(). | React.ReactNode | – |