Getting Started
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 and Tailwind CSS. Pick the question that sounds like you to jump to its answer and the pages that go deeper.
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.
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.
- Keyboard first: shortcuts for every view, and the live demo's command menu. See 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 guide sets up shadcn/ui and adds the @calendarcn registry to your components.json. Then add the full calendar with one command:
npx shadcn add @calendarcn/calendarOr add only the pieces you need. Each one pulls in the ones it builds on.
Calendar
The full calendar: a toolbar and view switcher over the day, week, month, year and agenda views.
Calendar App
The whole live demo in one install: both sidebars, the header, every view, the command menu and .ics files.
Calendar Core
CalendarProvider and useCalendar(), the state every view shares.
Time Grid
The scrollable hour grid behind the day and week views.
Day View
A single day on the time grid.
Week View
A week, or any number of days, on the time grid.
Month View
A month at a glance.
Agenda View
The next 30 days' events as a scrolling list, grouped by day.
Year View
Twelve months at a glance, with the days that have events marked.
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.
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
Who owns the events, and onEventCreate, onEventUpdate and
onEventSelect for saving one change at a time.
Loading Events
Fetch events for the dates on screen as people navigate, with a loading bar while they arrive.
Import and Export
Read and write .ics files, plus a recipe that syncs with Google Calendar.
Event fields
The four required fields, plus isAllDay for the all-day row and color
for one of the seven event colors.
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
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
renderEventContent draws inside each event. renderEventDetails replaces
the details popover.
Theming
Your shadcn/ui theme, plus --event-{color} tokens for the seven event
colors in light and dark mode.
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.
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
Preview an update, apply it, and put your own edits back.
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
Everything that's planned, roughly in priority order, and what shipped recently.
Suggest something
Missing something you need? Open an issue on GitHub and describe what you're building.
Built with
Next.js, React, Tailwind CSS, shadcn/ui and date-fns. The source is on GitHub under the MIT license.