RegistryInstall CalendarCN with the shadcn CLI

Components

Calendar Core

CalendarProvider and useCalendar(), the state and settings every view shares.

Calendar Core has no UI of its own. CalendarProvider holds the calendar's state (events, view, date, selection) and its settings, and useCalendar() reads and changes that state from any component inside it. Every view and the event details build on it. In the preview, the list on the right is the app's own events state: drag, resize or create an event and it updates.

Installation

pnpm dlx shadcn add @calendarcn/calendar-core

Usage

import { CalendarProvider, useCalendar } from "@/components/calendar-provider";
import { WeekView } from "@/components/week-view";

export function Schedule() {
  return (
    <CalendarProvider defaultEvents={events}>
      <Toolbar />
      <WeekView />
    </CalendarProvider>
  );
}

function Toolbar() {
  const { monthName, year, goToPrev, goToNext } = useCalendar();
  // ...
}

Controlled or uncontrolled

Each piece of state comes in a shadcn/Radix-style pair. Pass defaultEvents (or nothing) and the provider owns the events. Pass events with onEventsChange and your app owns them: the provider draws whatever events holds and reports every drag, resize, create and edit as the full next list. view, date and numberOfDays work the same way.

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

<CalendarProvider events={events} onEventsChange={setEvents}>
  <WeekView />
</CalendarProvider>;

Use onEventCreate, onEventUpdate, onEventDelete and onEventSelect to react to one change at a time, for example to save it to a server. onEventCreate also gets an occurrence of a repeating event the first time it is edited: see Repeating events. To fetch events for the dates on screen as people navigate, use onVisibleRangeChange and loading: see Loading Events.

Undo and redo

⌘Z

takes back the calendar's own changes, newest first: creating, moving, resizing and editing an event, and deleting, duplicating, cutting or pasting one.

⇧⌘Z

does them again, until a new change clears what's left to redo. undo(), redo(), canUndo and canRedo from useCalendar() do the same from your own buttons. Edits to one event less than a second apart, like a title typed letter by letter, are one step, and the provider keeps the last 100 steps.

Undo and redo report what they change like any other change: the full list through onEventsChange, then onEventCreate, onEventUpdate or onEventDelete for each event, so an app that saves one change at a time stays in sync. An undone delete adds the event back with its old id.

A step applies only while its events are the very objects the calendar left in events. Replace one from outside, by reloading your events from a server for example, and the steps that touch it can't be undone: canUndo turns false and the key goes back to the browser, so an undo never overwrites a newer version. Keep the objects you get in onEventsChange, as useState does, and undo keeps working. Changes your app makes to events itself, like an import, are not steps.

Selecting several events

As in Notion Calendar, Shift-click or ⌘-click (Ctrl-click on Windows and Linux) on an event adds it to the selection, and on a selected one takes it out. ⌘A (selectAllVisible) selects every event on the dates on screen. Esc, a click on empty space or a plain click on one event clears the rest. Several selected events are drawn selected but show no details, as in Notion Calendar, and selectedEventIds lists them.

On one of them, delete, cut, copy, duplicate and paste act on them all, from the keyboard, the right-click menu or deleteEvent, cutEvent, copyEvent and duplicateEvent, each as one undo step. The toasts read "2 events deleted" and "2 events cut" with Undo, and "2 events copied to clipboard". Pasted events keep their distance from the earliest of them, which lands where a single paste would. Dragging one of them, or moving it with Alt↓, moves them all by as much; resizing changes that event alone. A date of a repeating event among them changes alone, as its own event: an action on several events never asks which events of the series it applies to. With timeZone set, a moved group's events all move by the same time. Selecting other events while a change to a repeating date waits asks about that change first.

Notices

After a delete, a cut or a copy, the provider keeps a notice worded like Notion Calendar's toasts: "Event deleted" with the event's title and an undo, "Event cut" with an undo, "Event copied to clipboard" with the title. Calendar Toaster shows it; without one, nothing shows. useCalendarNotice() returns it, to show with a toast library of your own, and showNotice adds notices of yours. A notice's undo takes back that action and nothing else, so the notice closes as soon as another change is the latest, and its undo is there exactly while canUndo is.

Server rendering

Without date or defaultDate, the calendar starts on today's period. The server doesn't know the viewer's today or time zone, so in that case the provider renders nothing until hydration finishes, and server and client markup always match. Pass defaultDate to render on the server.

Creating events

New events start the way they do in Notion Calendar, as a draft:

  • Double-click an empty slot in the day or week view for a 30-minute draft there, or press and drag to draw one of any length: down, up, or across day columns. Both ends snap to snapMinutes.
  • Do the same in the all-day row or in the month view for an all-day draft over one day or several.
  • On touch, a long press starts the draft, and dragging on draws it.
  • A single click on empty space creates nothing. It clears the selection.

A draft is drawn and selected, with its title focused in the details, but it isn't in events yet. It is saved by its first edit: a title (on Enter, or when focus leaves the title) or a change to any other field. Saving adds it to events, calls onEventCreate once and is one step for undo. A draft that nothing was typed into is thrown away when the selection moves on: Esc (once to leave the title, once more for the draft), a click elsewhere, or another event. Esc in the middle of a drag drops it too.

While nothing is typed into it, a draft is a tinted range in its calendar's color. Its first title keystroke turns it into an event block that shows the title as you type.

  • createEvent builds the draft from its range. Return an untitled event, as the default does, for Notion Calendar's flow, or null to create nothing there. The range's isAllDay is set for whole days.
  • defaultEventDuration sets the length of a double-clicked event, in minutes.
  • C and the command menu's "Create event..." start a draft at the next half hour (addEventAtNextSlot()), drawn as an event block from the start, as in Notion Calendar.
  • useCalendar() returns the draft as eventDraft and starts one from your own button or command with startEventDraft(range), drawn the same way. updateEvent(draft) saves it, updateEventDraft(draft) changes it without saving, and clearSelection() throws it away.
  • addEventFromRange(range) still adds an event at once, with no draft.
function NewEventButton() {
  const { startEventDraft } = useCalendar();
  const start = new Date();
  start.setMinutes(Math.ceil(start.getMinutes() / 30) * 30, 0, 0);

  return (
    <Button
      onClick={() =>
        startEventDraft({ start, end: new Date(start.getTime() + 30 * 60_000) })
      }
    >
      New event
    </Button>
  );
}

Repeating events

An event with a recurrenceRule (or an RRULE in recurrence) is one event in events, and every view draws it on each date its rule gives, as does the details sidebar's search. The views generate those occurrences for the dates on screen with expandRecurringEvents(); they are never added to events, so useCalendar().events, onEventsChange and the .ics export hold each series once.

  • An occurrence's id is the series' id and its date, launch-2026-06-20. Selecting it, selectedEvent and the details' series arrows work as for any event.
  • Editing or deleting one date (drag, resize, the keyboard, the right-click menu or the details) asks which events it applies to: see Editing a repeating event. This event changes that date only. It is added to your events with seriesId (the series' id) and originalStart (the start it had), through onEventCreate and onEventsChange, and drawn in place of the generated one. Later edits to it go through onEventUpdate.
  • Cut on one date, and Delete with This event, leave it out of the series: its start is added to the series event's excludedDates (reported through onEventUpdate), and a stored date goes with it. Cut on the series' own event cuts the whole series. Undo and redo treat each as one step: the first edit of a generated date is a create, so undoing it brings the generated date back.
  • Duplicate and Paste on a date of a repeating event add a single event on that date: the copy has no seriesId, originalStart, recurrenceRule, recurrence or excludedDates, so it doesn't repeat and the series keeps its dates.
  • excludedDates leaves dates out, like an .ics EXDATE.
  • Occurrences keep the series' clock time in its timeZone when the clocks change. An all-day series keeps whole days.
  • recurrence written as display text ("Every week on Thu") is a label only: draw those occurrences as events of your own.

When you load events by range (Loading Events), include the repeating events whose series reaches into the range, even when their first date is earlier.

Editing a repeating event

A change to one date of a repeating event asks which events it applies to, as Notion Calendar does: This event, This and following events or All events (on the series' first date, only this event or all events; a repeat rule change, only the following or all events). A drag, a resize, an Alt arrow move or a change from the right-click menu asks at once. A change in the details waits: the date shows it on the calendar with a dot before its title, and the question comes when you leave the event, listing what changed. Save event applies it, Discard change drops it, Continue editing goes back to it, and so does Esc. A delete asks the same way, with Delete event and Cancel.

  • This event stores the date as an event of its own (with seriesId and originalStart), or, for a delete, adds its start to the series' excludedDates.
  • This and following events ends the series the day before (its end becomes that date) and starts a new series event, with a new id, from this date. A series that ends after a number of times keeps the count that's left. Later dates stored on their own move to the new series.
  • All events changes the series event. A new time moves every date; dates with a time of their own keep it. Deleting all events deletes the series and its stored dates.

When a date moves to another day, or the repeat rule changes, the stored dates and excluded dates it affects are removed: their days are no longer in the series.

Each answer is one undo step. onEventsChange gets the full list once, then onEventDelete, onEventUpdate and onEventCreate get each event the answer removed, changed or added, in that order, so a new series reaches your server before its dates. A change that waits is never reported. After an answer, a toast says what happened: Event deleted, All events deleted (both with Undo) or Event updated.

The views render the question with EventSeriesScopeDialog (@/components/event-series-scope-dialog). In a layout without them, render it once inside the provider; without it, a change applies to that date only (a repeat rule change, to that date and the following ones). To skip the question in your own code, pass the answer: updateEvent(event, "all") or deleteEvent(event.id, "this"). Custom details should change events with editEvent(event), which waits like the built-in details. getSeriesEditChanges() and getSeriesDeleteChanges() from @/lib/recurrence return the same changes without a provider.

View settings

viewSettings holds the view dropdown's three settings, and every view reads them: showWeekends, showDeclinedEvents and showWeekNumbers. Start with your own through defaultViewSettings, and flip them with toggleWeekends, toggleDeclinedEvents and toggleWeekNumbers, or let the view switcher and the Command Menu do it.

  • Who you are among the participants. An event is declined when your participant answered "declined": the one with self: true (Google Calendar's flag), or, without one, the one whose email is the event's calendarEmail. isDeclinedByViewer(event) says whether an event is, and filterDeclinedEvents(events, showDeclinedEvents) drops them while they're hidden, for a view of your own.
  • Days without the weekend. With weekends hidden, getShownDays(), addShownDays() and countShownDaysBetween() count weekdays instead of days, and getFirstShownDay() moves a Saturday or Sunday to Monday. getVisibleDays(), getPeriodStart() and getVisibleDayCount() take the setting as their last argument.

Hour size

The day and week views' hours fill the screen by default, at least 48px an hour. hourHeight on CalendarProvider sets another size, in pixels, and null goes back to the default. It lives in the provider so the Command Menu, the keys and your own controls all change the same size:

  • zoomHoursIn() and zoomHoursOut() step through HOUR_HEIGHT_STEPS (24, 32, 40, 48, 64, 80, 96, 128 and 160px), from the size on screen. resetHourHeight() goes back to the default. useCalendarShortcuts() runs them on ⇧⌘., ⇧⌘, and ⇧⌘0, Notion Calendar's keys.
  • Zooming keeps the time in the middle of the screen where it was. Dragging, resizing, creating, the current-time line and horizontal scrolling work at every size.
  • The size isn't stored. To keep it across visits, save onHourHeightChange's value and pass it back as defaultHourHeight (or control hourHeight).
// Your app's state: load it from wherever you keep preferences
const [hourHeight, setHourHeight] = React.useState<number | null>(null);

<CalendarProvider hourHeight={hourHeight} onHourHeightChange={setHourHeight}>
  <WeekView />
</CalendarProvider>;

Configuration

Display and interaction settings are plain props: a 24-hour clock, a date-fns locale for day and month names, the first day of the week, the visible hours of the time grid, the minute step that drag, resize and new events snap to, and the length of a double-clicked event. Events outside the visible hours are clipped at the edge, and hidden when they lie fully outside. Read the resolved settings anywhere with useCalendarConfig(), for example to format times in a custom renderer the way the calendar does.

Time zone

By default the calendar draws in each viewer's own time zone. timeZone takes an IANA zone, like "Asia/Tokyo", and draws the calendar on that zone's clock, as Notion Calendar's primary time zone: a team calendar in the office's zone, or a page your server renders the same for every visitor. Events sit at that zone's time, "today", the current-time line and the first day of each week follow it, a double-click on an empty slot starts the event at that row's time there, the details show times in it, and the time axis is labeled with it. In the preview the calendar is in Tokyo, with India's hours beside it, and "Your clock" lists the same events on your own clock.

<CalendarProvider
  events={events}
  onEventsChange={setEvents}
  timeZone="Asia/Tokyo"
>
  <WeekView />
</CalendarProvider>
  • What you pass in and get back stays instants: events, onEventsChange, onEventCreate, onEventUpdate and the range createEvent gets. onVisibleRangeChange gets the instants the days on screen start and end in that zone. Save and fetch as you do without it.
  • Inside the provider, times read on the calendar's clock. Events from useCalendar(), renderEventContent and renderEventDetails are Dates whose local time (getHours(), date-fns format()) is that zone's, and updateEvent takes them the same way. fromZonedWallClock(date, timeZone) from @/lib/time-zones, with timeZone from useCalendarConfig(), turns one back into an instant. To expand repeating events yourself, pass that timeZone to expandRecurringEvents().
  • Days are calendar dates: date, currentDate, visibleDays, useCalendar().visibleRange and all-day events are local midnights whose year, month and day name the day.
  • An event keeps its own timeZone, and one without it stays in the viewer's: a repeating meeting keeps its clock time there, and the details' time zone row shows that zone.
  • timeZone is the primary zone, so it changes from the time axis labels and the command menu too: pass onTimeZoneChange with it, or defaultTimeZone to let the provider own it.
  • A zone the runtime doesn't know is ignored, and the calendar draws in the viewer's.
  • On the one night a year the viewer's own clocks skip an hour, a time in that hour can't be drawn: an event there is drawn from the hour after, and keeps its times when you edit something else.

Additional time zones

secondaryTimeZones takes IANA time zones, like ["Asia/Kolkata"], and secondaryTimeZone one of them. The day and week views then show each zone's hours in a column left of the time axis, left to right, as Notion Calendar does with additional time zones. Each column has its zone's short label at the top, and the current-time line keeps its one time badge, in your column, as in Notion Calendar. A zone half an hour or 45 minutes off yours shows the minutes: beside your 10 AM, India's column reads 7:30 PM.

<CalendarProvider defaultEvents={events} secondaryTimeZone="Asia/Kolkata">
  <WeekView />
</CalendarProvider>

People change the zones from the time axis, as in Notion Calendar:

  • A click or right-click on a zone's label opens its menu: "Change time zone", "Make time zone primary" (or "Make time zone secondary" on the primary one) and "Remove time zone from list". The "+" left of "All-day" adds a zone, as the left-most column. Both lists search by city, zone name or offset ("+9", "GMT-3").

  • The zones are provider state like view: pass secondaryTimeZones with onSecondaryTimeZonesChange to keep them in your app, or defaultSecondaryTimeZones to let the provider own them. useCalendar().changeTimeZones() changes them from your own controls, with the helpers in @/lib/time-zones (addTimeZone, removeTimeZone, makeTimeZonePrimary, makeTimeZoneSecondary, replaceTimeZone).

  • The column shows one offset for every day on screen: the one at noon today while today is on screen, else at noon on the first day shown. In a week where either zone changes its clocks, it is off by that change on the days on the other side of it.

  • Each column is 64px wide at every screen size, so on a phone the days get less room. To show them on wide screens only, pass the prop there.

  • Screen readers read each zone's label once. Both columns' hours are hidden from them, like the time axis itself, since each event's label already reads its time.

  • A zone the runtime doesn't know gets no column.

  • Calendar and Calendar App take the props too. Calendar App's command menu adds one with "Show additional time zones...", and makes one primary or hides one with "Make time zone primary..." and "Hide time zone...".

Travel to a time zone

Notion Calendar's "Travel to time zone" draws the calendar in another zone for a while, without changing your zones: the zone travelled to gets a column next to the days, filled in the primary color, with your home zone beside it. useCalendar().travelToTimeZone(zone) travels and travelToTimeZone(null) travels back; travelTimeZone is the zone travelled to, or null at home.

  • In Calendar App, Z or "Travel to time zone..." in the command menu lists the zones to travel to.
  • The x on the travel label, "Travel back home" in its menu, and Esc with no event selected (with useCalendarShortcuts()) travel back. "Add as primary time zone" and "Add as secondary time zone" keep the zone.
  • Travelling isn't saved: a reload starts at home.

Meeting with people

contacts are also the people you can meet with, as in Notion Calendar's "Meet with...". useCalendarPeople() reads and changes who that is:

  • Meeting with someone (meetWith, addMeetWith): their events are drawn in the day and week views behind yours, hatched in their color with their initial, and the times when you and everyone you meet with are free are highlighted, inside workingHours (9 AM to 5 PM, Monday to Friday by default) and at least 30 minutes long. An event created meanwhile invites them: its draft starts with them in its participants, waiting for an answer, with the event's calendar account (calendarEmail) as the organizer. addEventFromRange() invites them the same way.
  • Showing a teammate's calendar (teammates, addTeammate): their events are drawn the same way, without a meeting: no free time, no invitations.

Their events come from contactEvents, keyed by email. Load them when someone is added (onMeetWithChange, onTeammatesChange) and when the dates on screen change (onVisibleRangeChange). From Google Calendar's free/busy API, which gives busy times without titles, pass an event titled "Busy" for each one. Repeating events work as yours do, and with timeZone or while travelling, their events and the working hours read on the calendar's clock, as yours do. All-day and multi-day events aren't drawn (an all-day event marked status: "busy" still takes the day out of the free time), and month, year and agenda views leave other people's events out.

const [meetWith, setMeetWith] = React.useState<string[]>([]);
const contactEvents = useFreeBusy(meetWith, visibleRange); // your loader

<CalendarProvider
  defaultEvents={events}
  contacts={contacts}
  meetWith={meetWith}
  onMeetWithChange={setMeetWith}
  contactEvents={contactEvents}
>
  <CalendarSidebar />
  <WeekView />
</CalendarProvider>;

The Calendar Sidebar's "Meet with..." field and the People Picker (F and P in Calendar App) add people; your own controls can call addMeetWith, addTeammate and the rest. getSharedFreeTime(calendars, days, options) in lib/free-busy.ts computes the highlighted free time, to list it elsewhere: it counts an event as busy unless it's marked status: "free", the calendar's owner declined it, or it's all-day (unless marked busy).

Custom event content

renderEventContent replaces what's drawn inside each event. The calendar keeps drawing the box (position, color, selection, drag and resize handles), so the renderer only returns the inside. placement says where the event is drawn and how much room it has: a timed block in the hour grid ("time-grid", as tall as the event), a 24px bar in the all-day row ("all-day"), a 20px line in month view ("month-item" and "month-bar"), or a row as wide as the agenda ("agenda"). isCompact is true wherever there's room for one line only.

To replace the details popover instead, see Event Details.

Typed events

Extend CalendarEvent with your own fields and pass your events in. The provider infers your type, and every callback and renderer gets it back. Read it in your own components with useCalendar<Meeting>().

Once your type has required fields, createEvent becomes required: the calendar can't fill room or attendees for a new event, so TypeScript asks you to.

interface Meeting extends CalendarEvent {
  room: string;
  attendees: string[];
}

<CalendarProvider
  defaultEvents={meetings}
  createEvent={(range) => ({
    id: crypto.randomUUID(),
    title: "",
    ...range,
    room: "Atlas",
    attendees: [],
  })}
>
  <WeekView />
</CalendarProvider>;

API Reference

CalendarProvider

TEvent is your event type: CalendarEvent plus your own fields. It's inferred from events or defaultEvents.

PropTypeDefault
events
Events to display (controlled). Pair with onEventsChange.
TEvent[]–
defaultEvents
Initial events when events is not controlled.
TEvent[][]
onEventsChange
Called with the full next list whenever events change: drag, resize, create, an edit in the details, delete, duplicate, cut, paste, undo and redo, and once for each answer to the [repeating event question](#editing-a-repeating-event). A repeating event stays one event; an edited occurrence is added as its own.
(events: TEvent[]) => void–
view
Active view (controlled).
"day" | "week" | "month" | "agenda" | "year"–
defaultView
Initial view when view is not controlled.
"day" | "week" | "month" | "agenda" | "year""week"
onViewChange
Called when the view changes.
(view: ViewType) => void–
date
First day of the displayed period (controlled).
Date–
defaultDate
Initial first day when date is not controlled. Defaults to today in day and agenda views, January 1 in year view, and the start of this week otherwise. Without date or defaultDate, nothing renders until hydration finishes.
Date–
onDateChange
Called when the displayed date changes, by navigation or by scrolling.
(date: Date) => void–
weekStartsOn
Day the week starts on, 0 for Sunday to 6 for Saturday (controlled). Every view and the mini calendar follow it.
0 | 1 | 2 | 3 | 4 | 5 | 6–
defaultWeekStartsOn
Initial week start when weekStartsOn is not controlled. "Start week on..." in the command menu changes it.
0 | 1 | 2 | 3 | 4 | 5 | 60
onWeekStartsOnChange
Called when the week start changes.
(weekStartsOn: WeekStartsOn) => void–
numberOfDays
Days the week view shows (controlled). Below 7, the columns start on the current day and previous/next move by that many days. From 7 up, they start on the week's first day and move by a week.
number–
defaultNumberOfDays
Initial number of days when numberOfDays is not controlled.
number7
onNumberOfDaysChange
Called when the number of days changes.
(numberOfDays: number) => void–
hourHeight
Height of an hour in the day and week views, in pixels (controlled). null is the default size, which fills the screen with the visible hours, at least 48px an hour. See [Hour size](#hour-size).
number | null–
defaultHourHeight
Initial hour height when hourHeight is not controlled.
number | nullnull
onHourHeightChange
Called when the hour height changes: zooming in or out, or back to the default size. Store it to keep the size across visits.
(hourHeight: number | null) => void–
defaultViewSettings
Initial display preferences. Toggle them later with toggleWeekends, toggleDeclinedEvents and toggleWeekNumbers.
Partial<ViewSettings>{ showWeekends: true, showDeclinedEvents: true, showWeekNumbers: false }
snapMinutes
Minute step that timed-event drag, resize and new events snap to. Also the shortest length a resize or a drawn event allows.
number15
defaultEventDuration
Length in minutes of an event created by double-clicking an empty time slot, as in Notion Calendar.
number30
dayStartHour
First hour (0–23) the day and week views show. Events before it are clipped at the top edge, and hidden when they end before it.
number0
dayEndHour
Hour (1–24) the day and week views end at, after dayStartHour. Events after it are clipped at the bottom edge, and hidden when they start after it.
number24
hourCycle
Clock style for every time label: "3 PM" or "15:00".
12 | 2412
locale
date-fns locale for day names, month names, dates and week numbers.
LocaleenUS
secondaryTimeZone
IANA time zone, e.g. "Asia/Kolkata", whose hours the day and week views show in a column left of the time axis. The one-zone form of secondaryTimeZones, which wins when both are set. A zone the runtime doesn't know is ignored. See [Additional time zones](#additional-time-zones).
string–
secondaryTimeZones
Additional IANA time zones, each in a column left of the time axis, left to right. Zones the runtime doesn't know are left out. See [Additional time zones](#additional-time-zones).
string[]–
defaultSecondaryTimeZones
Initial additional zones when secondaryTimeZones isn't controlled.
string[][]
onSecondaryTimeZonesChange
Called when the additional zones change from the time axis labels or the command menu.
(timeZones: string[]) => void–
timeZone
IANA time zone the views draw in, e.g. "Asia/Tokyo": events, today, the current-time line, week starts, new events and the details' times follow its clock. The events you pass in and get back stay instants. A zone the runtime doesn't know is ignored. Defaults to the viewer's zone. See [Time zone](#time-zone).
string–
defaultTimeZone
Initial timeZone when it isn't controlled. Defaults to the viewer's zone.
string–
onTimeZoneChange
Called when the primary zone changes from the time axis labels or the command menu ("Make time zone primary", "Add as primary time zone").
(timeZone: string) => void–
calendars
Calendars the details panel's calendar picker offers, grouped by account email, and the event context menu under "Block on calendar" (hidden when the list is empty). Picking one moves the event with moveEventToCalendar(). An event without its own color is drawn in its calendar's.
CalendarInfo[][]
contacts
People the details' participants field suggests: the recent ones on focus, the matches while typing. A typed email can be invited without one.
EventContact[][]
rooms
Meeting rooms the participants field lists under "View rooms and resources", and among the matches while typing. That list is hidden when this is empty.
EventRoom[][]
conferenceProviders
Video call services the details' Conferencing menu offers, each creating calls with its own createConference. The row is hidden when this is empty, unless the event already has a call.
ConferenceProviderOption[][]
locationSuggestions
Places the details' location field lists under the typed text while typing.
LocationSuggestion[][]
meetWith
Emails of the people you're meeting with (controlled): their events are drawn beside yours, the free time you share is highlighted, and an event created meanwhile invites them. See [Meeting with people](#meeting-with-people).
string[]–
defaultMeetWith
People met with at first when meetWith is not controlled.
string[][]
onMeetWithChange
Called with the new emails when someone is added to or taken out of the meeting.
(meetWith: string[]) => void–
teammates
Emails of the teammates whose calendars show beside yours (controlled), as "Show teammate calendar..." adds them.
string[]–
defaultTeammates
Teammates shown at first when teammates is not controlled.
string[][]
onTeammatesChange
Called with the new emails when a teammate's calendar is shown or hidden.
(teammates: string[]) => void–
contactEvents
Other people's events by email, drawn while you meet with them or show their calendar. Load them when someone is added or the dates on screen change.
Record<string, DetailedCalendarEvent[]>{}
workingHours
Days and hours, on the calendar's clock (its timeZone, else the viewer's), the free time you share with the people you meet with is looked for in.
WorkingHours9 AM to 5 PM, Monday to Friday
createEvent
Builds a new event for a range: the draft drawn on the calendar, or the event addEventFromRange adds. Return null to create nothing. Defaults to an untitled event with a random UUID. Required when TEvent has required fields of its own.
(range: NewEventRange) => TEvent | null–
onEventCreate
Called after an event is added: a draft saved by its first edit, one addEventFromRange adds, a duplicate or a paste, an occurrence of a repeating event stored on its first edit (with seriesId and originalStart), the new series that **This and following events** starts and the dates it takes over, or one undo or redo brings back. A draft that is thrown away is never reported.
(event: TEvent) => void–
onEventUpdate
Called after an event changes: drag, resize, keyboard move, an edit in the details, a series and its dates an answer to the [repeating event question](#editing-a-repeating-event) changes, or undo and redo changing it back.
(event: TEvent) => void–
onEventDelete
Called after an event is removed: deleted, cut, or taken away by undo or redo (an undone create, duplicate or paste).
(event: TEvent) => void–
onEventSelect
Called whenever an event is selected: clicked, just added, or a draft that was just drawn (with the id it keeps once it is saved).
(eventId: string) => void–
onVisibleRangeChange
Called with the dates the view draws: once after it mounts, then each time they change (navigation, a view switch, a sideways scroll once it snaps). Never twice in a row for the same range. See [Loading Events](/docs/loading-events).
(range: VisibleRange) => void–
loading
Shows a thin progress bar under the day headers of every view, for example while events for a new range load. The calendar stays usable.
booleanfalse
renderEventContent
Draws the inside of each event in the hour grid, the all-day row and month view. Defaults to the title and time.
(props: EventContentProps<TEvent>) => ReactNode–
renderEventDetails
Draws the body of the details popover. Defaults to EventDetailPanel.
(props: EventDetailsRenderProps<TEvent>) => ReactNode–
children
The views and your own components that read calendar state.
ReactNode–

useCalendar()

Returns the state and actions of the nearest CalendarProvider. Pass your event type, useCalendar<TEvent>(), to get events and callbacks typed with it. Throws outside a provider.

FieldType
events
The stored events. A repeating event is one event here; expandRecurringEvents() gives its occurrences. With timeZone, their times read on that zone's clock: see [Time zone](#time-zone).
TEvent[]
view
Active view.
"day" | "week" | "month" | "agenda" | "year"
currentDate
First day of the displayed period.
Date
weekStartsOn
Day the week starts on.
0 | 1 | 2 | 3 | 4 | 5 | 6
numberOfDays
Days the week view shows.
number
hourHeight
Height of an hour in the day and week views, in pixels, or null at the default size, which fills the screen.
number | null
viewSettings
showWeekends, showDeclinedEvents and showWeekNumbers, which every view reads. See [Calendar Header](/docs/components/calendar-header#calendarviewswitcher).
ViewSettings
visibleDays
Days the day or week view shows right now, updated live while it scrolls sideways, or the 30 days the agenda lists. Empty in month and year view.
Date[]
displayMonth
First day of the month the month view shows (it follows its scroll), or null before month view has rendered.
Date | null
visibleRange
Dates the view draws, end exclusive: the days on screen in day and week view, the whole six-week grid in month view, the 30 days the agenda lists, the whole year in year view. A sideways scroll moves it once it snaps.
VisibleRange
loading
Whether the provider's loading prop is set.
boolean
selectedEventId
ID of the selected event. null while several are selected: selectedEventIds lists them, and none shows its details.
string | null
selectedEventIds
IDs of every selected event, in the order they were picked: the one selectedEventId names, or several. Empty when nothing is selected.
string[]
selectedEvent
The selected event: a stored one, or the generated occurrence its id names.
TEvent | null
previousInSeries
The selected event's previous occurrence in its repeating series (findSeriesOccurrence): { id, start, event }, with event the one stored for that date or the one generated for it. null when nothing is selected, the event doesn't repeat, or it is the first.
SeriesOccurrence<TEvent> | null
nextInSeries
The selected event's next occurrence in its series, or null at the series' end.
SeriesOccurrence<TEvent> | null
showSeriesOccurrence
Selects an occurrence and moves to its period when it is off screen. Nothing is added: a generated occurrence is selected as it is. The details' series arrows call it.
(occurrence: SeriesOccurrence<TEvent>) => void
timeZones
The zones beside the time axis: primary (timeZone, undefined for the viewer's) and secondary, left to right.
CalendarTimeZones
changeTimeZones
Changes the zones. change gets them with the primary one resolved (the viewer's when unset); build it with addTimeZone, removeTimeZone, makeTimeZonePrimary, makeTimeZoneSecondary or replaceTimeZone from @/lib/time-zones.
(change: (zones: CalendarTimeZones) => CalendarTimeZones) => void
travelTimeZone
The zone the calendar travelled to, drawn as the primary one, or null at home. See [Travel to a time zone](#travel-to-a-time-zone).
string | null
travelToTimeZone
Travels to a zone; null travels back home.
(timeZone: string | null) => void
highlightedDate
Day briefly highlighted after showDay.
Date | null
monthName
Month name for a header, in the calendar's locale ("October"). Week and day views use the last visible day, so a week that crosses into the next month shows the later month. Empty in year view, where a title shows the year alone.
string
year
Four-digit year for a header ("2026").
string
weekNumber
Week number of the displayed week.
number
goToToday
Goes to the period that contains today.
() => void
goToPrev
Goes back one period: a day, a week (or numberOfDays), a month, a year or the agenda's 30 days.
() => void
goToNext
Goes forward one period.
() => void
goToDate
Sets the first displayed day as given, without snapping to a week start.
(date: Date) => void
switchView
Switches the view and snaps the date to the new view's period.
(view: ViewType) => void
setNumberOfDays
Sets how many days the week view shows.
(numberOfDays: number) => void
setWeekStartsOn
Starts the week on another day. A full week or month on screen moves to the week that starts on that day around its middle, so most of the same dates stay.
(weekStartsOn: WeekStartsOn) => void
zoomHoursIn
Makes the hours one step taller (HOUR_HEIGHT_STEPS), up to 160px.
() => void
zoomHoursOut
Makes the hours one step shorter (HOUR_HEIGHT_STEPS), down to 24px.
() => void
resetHourHeight
Goes back to the default hour size, which fills the screen.
() => void
selectEvent
Selects an event, which opens its popover.
(eventId: string) => void
clearSelection
Clears the selection and closes the popover. Throws an unsaved eventDraft away, or saves it when a title was typed into it.
() => void
eventDraft
The event being created: drawn and selected, but not in events yet. See [Creating events](#creating-events).
TEvent | null
startEventDraft
Starts a draft for a range through createEvent, selects it and focuses its title. Nothing is stored, and onEventCreate isn't called, until its first edit saves it.
(range: NewEventRange) => void
updateEventDraft
Changes the draft without saving it, to preview what is being typed. Ignored unless the event has the draft's id.
(event: TEvent) => void
setSelectedEventIds
Selects these events: none clears the selection, one selects it as selectEvent does, several select them together.
(eventIds: string[]) => void
toggleEventSelection
Adds an event to the selection, or takes it out: what Shift- and Cmd-click do.
(eventId: string) => void
selectAllVisible
Selects every event on the dates on screen, scrolled-out hours too (Notion Calendar's Select all visible, ⌘A). Does nothing in year view.
() => void
addEventFromRange
Adds an event for a range through createEvent at once, selects it and focuses its title. startEventDraft waits for a first edit instead.
(range: NewEventRange) => void
updateEvent
Replaces the event with the same id. For a date of a repeating event, a view first asks which events the change applies to; scope ("this", "following" or "all") applies it without asking. A generated occurrence changed with "this" is added instead, through onEventCreate: see [Repeating events](#repeating-events). The eventDraft is saved instead: see [Creating events](#creating-events).
(event: TEvent, scope?: SeriesEditScope) => void
editEvent
Changes the event the way the details do: a selected date of a repeating event waits, marked with a dot, and asks once it is left. Other events change at once, and the eventDraft is saved.
(event: TEvent) => void
deleteEvent
Deletes the event through onEventsChange and onEventDelete, and clears the selection when it was selected. Undoable. For a date of a repeating event, a view first asks which events to delete; scope ("this", "following" or "all") deletes them without asking.
(eventId: string, scope?: SeriesEditScope) => void
duplicateEvent
Adds a copy of the event at the same time, with a new id from crypto.randomUUID(), through onEventsChange and onEventCreate, and selects it. Undoable.
(eventId: string) => void
copyEvent
Keeps a copy of the event for pasteEvent. Changes no event.
(eventId: string) => void
cutEvent
Keeps a copy of the event for pasteEvent, then deletes it. Undoable.
(eventId: string) => void
pasteEvent
Adds a copy of the cut or copied event, with a new id, and selects it: at the time slot under the mouse in day and week view, on the day under it in month view at the event's own time of day, else today or the first day on screen. All-day events stay all-day. Does nothing when nothing was cut or copied. Undoable.
() => void
undo
Undoes the latest create, move, resize, edit, delete, duplicate, cut or paste: reports it through onEventsChange and onEventCreate, onEventUpdate or onEventDelete, and selects the event it brings back or changes.
() => void
redo
Does again the latest step undo took back.
() => void
canUndo
Whether undo has a step to take back: false with none, or once the app replaced or removed one of that step's events itself. See [Undo and redo](#undo-and-redo).
boolean
canRedo
Whether redo has a step to do again. Any new change clears them.
boolean
toggleWeekends
Shows or hides the weekend in every view. Hiding it in day view, or with fewer than 7 days, moves a Saturday or Sunday on screen to Monday.
() => void
toggleDeclinedEvents
Shows or hides the events you declined (see isDeclinedByViewer). Hiding them clears the selection when the selected event is one.
() => void
toggleWeekNumbers
Shows or hides week numbers.
() => void
showDay
Opens the week containing date and briefly highlights that day.
(date: Date) => void
navigateToDate
Shows the period that contains date in the current view, as Go to date in the [Command Menu](/docs/components/command-menu) does, and briefly highlights that day in the day and week views.
(date: Date) => void
addEventAtNextSlot
Starts a draft at the next half hour, as Notion Calendar's C does: on today when it's on screen, else on the day Go to date just highlighted, else on the first day shown. defaultEventDuration long, or all-day in month view. Goes through startEventDraft: drawn as an event with its title focused, and stored by its first edit.
() => void

useCalendarConfig()

Returns the resolved settings of the nearest provider. Outside a provider it returns the defaults, so components like EventDetailPanel work on their own.

FieldType
snapMinutes
Snap step in minutes.
number
defaultEventDuration
Length in minutes of a double-clicked event.
number
dayStartHour
First visible hour, normalized to 0–23.
number
dayEndHour
Last visible hour, normalized to after dayStartHour and at most 24.
number
hourCycle
Clock style.
12 | 24
locale
date-fns locale.
Locale
secondaryTimeZone
IANA id of the first additional time zone column, or undefined when there is none.
string | undefined
secondaryTimeZones
IANA ids of the additional time zone columns, left to right, without zones the runtime doesn't know.
string[]
timeZone
IANA zone the views draw in (the zone travelled to while travelling), or undefined for the viewer's own. Pass it to fromZonedWallClock() to turn an event time from useCalendar() into an instant, and to the clock hooks.
string | undefined
weekStartsOn
First day of the week, for date pickers. Unset outside a provider, where the locale's applies.
0 | 1 | 2 | 3 | 4 | 5 | 6
calendars
Calendars the calendar picker and the context menu offer. Pass them to resolveEventColor(event, calendars) to draw an event in the color the calendar does.
CalendarInfo[]
contacts
People the participants field suggests.
EventContact[]
rooms
Meeting rooms the participants field offers.
EventRoom[]
conferenceProviders
Video call services the details offer.
ConferenceProviderOption[]
locationSuggestions
Places the location field suggests.
LocationSuggestion[]

useCalendarPeople()

Returns who you meet with and which teammates show, their events, and the actions that change them. Outside a provider nobody shows, and the actions do nothing. Emails are compared without case, and a list never holds one twice.

FieldType
contacts
The provider's contacts: the people you can add.
EventContact[]
meetWith
Emails of the people you're meeting with, in the order added.
string[]
teammates
Emails of the teammates whose calendars show.
string[]
shownPeople
Everyone whose events are drawn: the people you meet with, then the teammates not among them, each with the color their events take.
CalendarPerson[]
addMeetWith
Adds someone to the meeting.
(email: string) => void
removeMeetWith
Takes someone out of the meeting.
(email: string) => void
clearMeetWith
Ends the meeting: nobody is met with anymore.
() => void
addTeammate
Shows a teammate's calendar.
(email: string) => void
removeTeammate
Hides a teammate's calendar again.
(email: string) => void
getPersonEvents
A person's events from contactEvents, or an empty list when it has none for them.
(email: string) => DetailedCalendarEvent[]
workingHours
The provider's workingHours, or the default.
WorkingHours

useCalendarNotice()

Returns the notice to show and the functions that show and close one. One notice at a time: a new one replaces the last. Outside a provider it returns no notice, and both functions do nothing.

FieldType
notice
The notice to show now, or null.
CalendarNotice | null
showNotice
Shows a notice of your own in place of the one on screen, and reads its message and title in the live region.
(notice: Omit<CalendarNotice, "id">) => void
dismissNotice
Closes the notice with this id. Does nothing once a newer one replaced it.
(id: number) => void

CalendarNotice

FieldType
id (required)
Counts up with every notice, so a repeated message is a new toast.
number
message (required)
The first line, e.g. "Event deleted".
string
title
The second line: an event's title, which Calendar Toaster shows in curly quotes.
string
onUndo
Takes the action back. Calendar Toaster shows an Undo button only with it.
() => void

CalendarEvent

The fields the calendar needs to place and draw an event. DetailedCalendarEvent adds the fields the default details panel reads and edits.

FieldType
id (required)
Unique identifier.
string
title (required)
Event title.
string
start (required)
Start date and time.
Date
end (required)
End date and time. For an all-day event, the start of its last day, so a one-day event has start equal to end.
Date
isAllDay
Draws the event in the all-day row. Timed events that cross midnight go there too.
boolean
color
The event's own color, from the --event-* theme tokens. Without one it's drawn in its calendar's color (the CalendarInfo its calendarId names), else blue. resolveEventColor(event, calendars) from @/lib/event-utils returns the color an event is drawn in.
"red" | "orange" | "yellow" | "green" | "blue" | "purple" | "gray"

EventContentProps

Passed to renderEventContent.

FieldType
event
The event, with its in-progress start and end while it's dragged or resized.
TEvent
view
View the event is drawn in.
"day" | "week" | "month" | "agenda" | "year"
placement
Where the event is drawn, which sets how much room it has.
"time-grid" | "all-day" | "month-item" | "month-bar" | "agenda"
isSelected
Whether the event is selected.
boolean
isPast
Whether the event has already ended.
boolean
isDragging
Whether this is the copy that follows the pointer while dragging.
boolean
isResizing
Whether the event is being resized.
boolean
isCompact
Whether there's room for one line only: hour-grid blocks under 40px tall, and always in the all-day row and month view.
boolean
timeLabel
Time the default content shows: the range in the hour grid and the agenda ("10–11 AM", "All day"), the start in month cells and for timed all-day-row events ("9 AM"). Empty where the default shows no time.
string

NewEventRange

Passed to createEvent, startEventDraft and addEventFromRange: the slot that was double-clicked, the range that was dragged over, or the days picked in the all-day row or the month view.

FieldType
start
Start, snapped to snapMinutes. For whole days, midnight that starts the first day.
Date
end
End: defaultEventDuration after the start for a double-clicked slot (kept inside the visible hours and that day), the other end of a dragged range, or, for whole days, midnight that starts the last day.
Date
isAllDay
Set when the range covers whole days: it comes from the all-day row or the month view, and the new event is all-day.
boolean

VisibleRange

Passed to onVisibleRangeChange and returned as visibleRange. Both dates are local midnights.

FieldType
start
Midnight that starts the first visible day.
Date
end
Midnight after the last visible day (exclusive).
Date

CalendarInfo

An entry of the calendars prop.

FieldType
id (required)
Stored in the event's calendarId when picked.
string
name (required)
Display name.
string
color (required)
Swatch color shown beside the name. Events without their own color are drawn in it, and an event moved here that was drawn in its old calendar's color takes this one.
EventColor
email
Account the calendar belongs to. The picker and the menu group calendars by it, and a moved event's calendarEmail becomes it.
string
defaultReminders
Reminders of events on this calendar. Only moving an event applies them: an event moved here that still has its old calendar's defaults takes these, and reminders edited by hand stay. Creating an event never adds them, so give new events reminders in createEvent.
EventReminder[]

Calendar and reminder helpers

Exported from @/lib/event-utils. The views, the details panel and the context menu use them, so your own UI can draw and edit events the same way.

HelperType
resolveEventColor
The color an event is drawn in: its own color, else its calendar's, else DEFAULT_EVENT_COLOR.
(event, calendars) => EventColor
DEFAULT_EVENT_COLOR
"blue", for an event without a color whose calendar isn't listed.
EventColor
moveEventToCalendar
The event moved to the calendar to, as the picker does it: an event drawn in its old calendar's color takes the new one's, one with its old calendar's defaultReminders takes the new ones, and calendarEmail becomes to.email.
(event, to, calendars) => TEvent
groupCalendarsByEmail
Calendars grouped by account email ({ email?, calendars }), in the order given.
(calendars) => CalendarGroup[]
addReminder
The reminders with one added, sorted by when each fires. Returns reminders itself when one firing at the same moment is already set.
(reminders, reminder) => EventReminder[]
getReminderMinutes
Minutes before the start a reminder fires. An all-day reminder's time counts from the event's midnight start, so "1 day before at 9 AM" is 900.
(reminder) => number
isSameReminder
Whether two reminders fire at the same moment, as 60 min and 1 hour do.
(a, b) => boolean

Repeat helpers

Exported from @/lib/recurrence. The views and the provider use them, so a view of your own can draw and edit repeating events the same way.

HelperType
expandRecurringEvents
What to draw for the dates in range: events that don't repeat as they are, and each repeating event's occurrences that overlap the range, its first date as the event itself. At most MAX_OCCURRENCES_PER_RANGE (1000) per series. With the calendar's timeZone (useCalendarConfig().timeZone), events, range and the events returned read on that zone's clock, as useCalendar() hands them out; each series still repeats in its own zone.
(events, range: VisibleRange, timeZone?: string) => TEvent[]
findEventOrOccurrence
The stored event with that id, else the generated occurrence it names (launch-2026-06-20), else null. With the calendar's timeZone, events and the event returned read on that zone's clock.
(events, id, timeZone?: string) => TEvent | null
applyRecurringEdit
The event to store for an edit of one event: an occurrence keeps seriesId and originalStart unless its rule changed, and the series' event moved to another day takes its rule along.
(events, previous, edited) => TEvent
findEventSeries
The stored series event a drawn date belongs to (the event itself on its first date), or null for an event that doesn't repeat.
(events, event) => TEvent | null
getSeriesEditScopes
The options the question offers for a change: ["this", "following", "all"], without "following" on the first date and without "this" for a repeat rule change. Empty when nothing changed or the event doesn't repeat.
(events, before, after) => SeriesEditScope[]
getSeriesDeleteScopes
The options for deleting a date: ["this", "all"] on the first date, else all three.
(events, event) => SeriesEditScope[]
getSeriesEditChanges
What an answer changes: the deletes, updates and creates to apply and report as one undo step, in that order, and the id the changed date is drawn under afterwards.
(options: SeriesEditOptions) => SeriesEditResult
getSeriesDeleteChanges
What deleting a date with an option changes, in the same order.
(options: SeriesDeleteOptions) => EventHistoryChange[]

EventContact

An entry of the contacts prop.

FieldType
email (required)
Address, the participant's identity once invited.
string
name
Display name. Defaults to the email.
string
recent
Listed on focus, before typing, with a history icon, as a recently invited contact.
boolean
color
Color their events are drawn in while you meet with them or show their calendar. Defaults to one picked from their place in contacts.
EventColor

WorkingHours

The workingHours prop: when the free time you share with the people you meet with is looked for, on the calendar's clock (its timeZone, else the viewer's).

FieldType
days (required)
Days of the week they apply to, 0 (Sunday) to 6 (Saturday).
(0 | 1 | 2 | 3 | 4 | 5 | 6)[]
startHour (required)
Hour (0-23) they start at.
number
endHour (required)
Hour (1-24) they end at, after startHour.
number

CalendarPerson

An entry of useCalendarPeople().shownPeople: an EventContact (a bare { email } for an address not in contacts) whose color is always set, to the contact's own or the one picked for them.

ConferenceProviderOption

An entry of the conferenceProviders prop: one item of the Conferencing menu. None is on by default and none carries a service's brand: pass your own logos through icon. @calendarcn/conference-providers has placeholder Google Meet, Zoom and Microsoft Teams options to start from.

FieldType
provider (required)
Service the call is hosted on, stored in the call.
"google-meet" | "zoom" | "microsoft-teams" | "other"
label (required)
Name shown in the menu and on the event, unique among the options. Stored in the call, which tells apart two options of the same provider.
string
icon
16px icon in the menu and on the event. Defaults to a camera.
React.ReactNode
hint
Muted text at the end of the menu item, e.g. "Connect".
string
createConference (required)
Creates the call for the event, e.g. through the service's API. The row shows the option as pending until a returned promise settles; a rejected one adds no call, and a call that arrives after the panel moved to another event is dropped.
(event: DetailedCalendarEvent) => EventConference | Promise<EventConference>
const conferenceProviders: ConferenceProviderOption[] = [
  {
    provider: "zoom",
    label: "Zoom",
    icon: <ZoomIcon />,
    // Your server asks Zoom for a meeting
    createConference: async (event) => {
      const meeting = await createZoomMeeting(event.title);
      return { provider: "zoom", url: meeting.joinUrl, meetingId: meeting.id };
    },
  },
];

<CalendarProvider conferenceProviders={conferenceProviders}>
  <WeekView />
</CalendarProvider>;

LocationSuggestion

An entry of the locationSuggestions prop.

FieldType
name (required)
Name of the place, e.g. "Central Park".
string
address
Shown under the name, and saved after it: "Central Park, New York, NY, USA".
string

On this page