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-coreUsage
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
⌘Ztakes back the calendar's own changes, newest first: creating, moving, resizing and editing an event, and deleting, duplicating, cutting or pasting one.
⇧⌘Zdoes 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.
createEventbuilds the draft from its range. Return an untitled event, as the default does, for Notion Calendar's flow, ornullto create nothing there. The range'sisAllDayis set for whole days.defaultEventDurationsets 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 aseventDraftand starts one from your own button or command withstartEventDraft(range), drawn the same way.updateEvent(draft)saves it,updateEventDraft(draft)changes it without saving, andclearSelection()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,selectedEventand 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) andoriginalStart(the start it had), throughonEventCreateandonEventsChange, and drawn in place of the generated one. Later edits to it go throughonEventUpdate. - 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 throughonEventUpdate), 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,recurrenceorexcludedDates, so it doesn't repeat and the series keeps its dates. excludedDatesleaves dates out, like an .icsEXDATE.- Occurrences keep the series' clock time in its
timeZonewhen the clocks change. An all-day series keeps whole days. recurrencewritten 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
seriesIdandoriginalStart), or, for a delete, adds its start to the series'excludedDates. - This and following events ends the series the day before (its
endbecomes 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'scalendarEmail.isDeclinedByViewer(event)says whether an event is, andfilterDeclinedEvents(events, showDeclinedEvents)drops them while they're hidden, for a view of your own. - Days without the weekend. With weekends hidden,
getShownDays(),addShownDays()andcountShownDaysBetween()count weekdays instead of days, andgetFirstShownDay()moves a Saturday or Sunday to Monday.getVisibleDays(),getPeriodStart()andgetVisibleDayCount()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()andzoomHoursOut()step throughHOUR_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 asdefaultHourHeight(or controlhourHeight).
// 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,onEventUpdateand the rangecreateEventgets.onVisibleRangeChangegets 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(),renderEventContentandrenderEventDetailsareDates whose local time (getHours(), date-fnsformat()) is that zone's, andupdateEventtakes them the same way.fromZonedWallClock(date, timeZone)from@/lib/time-zones, withtimeZonefromuseCalendarConfig(), turns one back into an instant. To expand repeating events yourself, pass thattimeZonetoexpandRecurringEvents(). - Days are calendar dates:
date,currentDate,visibleDays,useCalendar().visibleRangeand 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. timeZoneis the primary zone, so it changes from the time axis labels and the command menu too: passonTimeZoneChangewith it, ordefaultTimeZoneto 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: passsecondaryTimeZoneswithonSecondaryTimeZonesChangeto keep them in your app, ordefaultSecondaryTimeZonesto 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, insideworkingHours(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 itsparticipants, 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.
| Prop | Type | Default |
|---|---|---|
eventsEvents to display (controlled). Pair with onEventsChange. | TEvent[] | – |
defaultEventsInitial events when events is not controlled. | TEvent[] | [] |
onEventsChangeCalled 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 | – |
viewActive view (controlled). | "day" | "week" | "month" | "agenda" | "year" | – |
defaultViewInitial view when view is not controlled. | "day" | "week" | "month" | "agenda" | "year" | "week" |
onViewChangeCalled when the view changes. | (view: ViewType) => void | – |
dateFirst day of the displayed period (controlled). | Date | – |
defaultDateInitial 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 | – |
onDateChangeCalled when the displayed date changes, by navigation or by scrolling. | (date: Date) => void | – |
weekStartsOnDay 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 | – |
defaultWeekStartsOnInitial week start when weekStartsOn is not controlled. "Start week on..." in the command menu changes it. | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 0 |
onWeekStartsOnChangeCalled when the week start changes. | (weekStartsOn: WeekStartsOn) => void | – |
numberOfDaysDays 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 | – |
defaultNumberOfDaysInitial number of days when numberOfDays is not controlled. | number | 7 |
onNumberOfDaysChangeCalled when the number of days changes. | (numberOfDays: number) => void | – |
hourHeightHeight 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 | – |
defaultHourHeightInitial hour height when hourHeight is not controlled. | number | null | null |
onHourHeightChangeCalled 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 | – |
defaultViewSettingsInitial display preferences. Toggle them later with toggleWeekends, toggleDeclinedEvents and toggleWeekNumbers. | Partial<ViewSettings> | { showWeekends: true, showDeclinedEvents: true, showWeekNumbers: false } |
snapMinutesMinute step that timed-event drag, resize and new events snap to. Also the shortest length a resize or a drawn event allows. | number | 15 |
defaultEventDurationLength in minutes of an event created by double-clicking an empty time slot, as in Notion Calendar. | number | 30 |
dayStartHourFirst 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. | number | 0 |
dayEndHourHour (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. | number | 24 |
hourCycleClock style for every time label: "3 PM" or "15:00". | 12 | 24 | 12 |
localedate-fns locale for day names, month names, dates and week numbers. | Locale | enUS |
secondaryTimeZoneIANA 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 | – |
secondaryTimeZonesAdditional 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[] | – |
defaultSecondaryTimeZonesInitial additional zones when secondaryTimeZones isn't controlled. | string[] | [] |
onSecondaryTimeZonesChangeCalled when the additional zones change from the time axis labels or the command menu. | (timeZones: string[]) => void | – |
timeZoneIANA 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 | – |
defaultTimeZoneInitial timeZone when it isn't controlled. Defaults to the viewer's zone. | string | – |
onTimeZoneChangeCalled 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 | – |
calendarsCalendars 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[] | [] |
contactsPeople the details' participants field suggests: the recent ones on focus, the matches while typing. A typed email can be invited without one. | EventContact[] | [] |
roomsMeeting 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[] | [] |
conferenceProvidersVideo 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[] | [] |
locationSuggestionsPlaces the details' location field lists under the typed text while typing. | LocationSuggestion[] | [] |
meetWithEmails 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[] | – |
defaultMeetWithPeople met with at first when meetWith is not controlled. | string[] | [] |
onMeetWithChangeCalled with the new emails when someone is added to or taken out of the meeting. | (meetWith: string[]) => void | – |
teammatesEmails of the teammates whose calendars show beside yours (controlled), as "Show teammate calendar..." adds them. | string[] | – |
defaultTeammatesTeammates shown at first when teammates is not controlled. | string[] | [] |
onTeammatesChangeCalled with the new emails when a teammate's calendar is shown or hidden. | (teammates: string[]) => void | – |
contactEventsOther 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[]> | {} |
workingHoursDays 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. | WorkingHours | 9 AM to 5 PM, Monday to Friday |
createEventBuilds 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 | – |
onEventCreateCalled 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 | – |
onEventUpdateCalled 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 | – |
onEventDeleteCalled after an event is removed: deleted, cut, or taken away by undo or redo (an undone create, duplicate or paste). | (event: TEvent) => void | – |
onEventSelectCalled 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 | – |
onVisibleRangeChangeCalled 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 | – |
loadingShows a thin progress bar under the day headers of every view, for example while events for a new range load. The calendar stays usable. | boolean | false |
renderEventContentDraws 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 | – |
renderEventDetailsDraws the body of the details popover. Defaults to EventDetailPanel. | (props: EventDetailsRenderProps<TEvent>) => ReactNode | – |
childrenThe 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.
| Field | Type |
|---|---|
eventsThe 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[] |
viewActive view. | "day" | "week" | "month" | "agenda" | "year" |
currentDateFirst day of the displayed period. | Date |
weekStartsOnDay the week starts on. | 0 | 1 | 2 | 3 | 4 | 5 | 6 |
numberOfDaysDays the week view shows. | number |
hourHeightHeight of an hour in the day and week views, in pixels, or null at the default size, which fills the screen. | number | null |
viewSettingsshowWeekends, showDeclinedEvents and showWeekNumbers, which every view reads. See [Calendar Header](/docs/components/calendar-header#calendarviewswitcher). | ViewSettings |
visibleDaysDays 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[] |
displayMonthFirst day of the month the month view shows (it follows its scroll), or null before month view has rendered. | Date | null |
visibleRangeDates 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 |
loadingWhether the provider's loading prop is set. | boolean |
selectedEventIdID of the selected event. null while several are selected: selectedEventIds lists them, and none shows its details. | string | null |
selectedEventIdsIDs of every selected event, in the order they were picked: the one selectedEventId names, or several. Empty when nothing is selected. | string[] |
selectedEventThe selected event: a stored one, or the generated occurrence its id names. | TEvent | null |
previousInSeriesThe 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 |
nextInSeriesThe selected event's next occurrence in its series, or null at the series' end. | SeriesOccurrence<TEvent> | null |
showSeriesOccurrenceSelects 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 |
timeZonesThe zones beside the time axis: primary (timeZone, undefined for the viewer's) and secondary, left to right. | CalendarTimeZones |
changeTimeZonesChanges 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 |
travelTimeZoneThe 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 |
travelToTimeZoneTravels to a zone; null travels back home. | (timeZone: string | null) => void |
highlightedDateDay briefly highlighted after showDay. | Date | null |
monthNameMonth 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 |
yearFour-digit year for a header ("2026"). | string |
weekNumberWeek number of the displayed week. | number |
goToTodayGoes to the period that contains today. | () => void |
goToPrevGoes back one period: a day, a week (or numberOfDays), a month, a year or the agenda's 30 days. | () => void |
goToNextGoes forward one period. | () => void |
goToDateSets the first displayed day as given, without snapping to a week start. | (date: Date) => void |
switchViewSwitches the view and snaps the date to the new view's period. | (view: ViewType) => void |
setNumberOfDaysSets how many days the week view shows. | (numberOfDays: number) => void |
setWeekStartsOnStarts 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 |
zoomHoursInMakes the hours one step taller ( HOUR_HEIGHT_STEPS), up to 160px. | () => void |
zoomHoursOutMakes the hours one step shorter ( HOUR_HEIGHT_STEPS), down to 24px. | () => void |
resetHourHeightGoes back to the default hour size, which fills the screen. | () => void |
selectEventSelects an event, which opens its popover. | (eventId: string) => void |
clearSelectionClears the selection and closes the popover. Throws an unsaved eventDraft away, or saves it when a title was typed into it. | () => void |
eventDraftThe event being created: drawn and selected, but not in events yet. See [Creating events](#creating-events). | TEvent | null |
startEventDraftStarts 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 |
updateEventDraftChanges the draft without saving it, to preview what is being typed. Ignored unless the event has the draft's id. | (event: TEvent) => void |
setSelectedEventIdsSelects these events: none clears the selection, one selects it as selectEvent does, several select them together. | (eventIds: string[]) => void |
toggleEventSelectionAdds an event to the selection, or takes it out: what Shift- and Cmd-click do. | (eventId: string) => void |
selectAllVisibleSelects every event on the dates on screen, scrolled-out hours too (Notion Calendar's Select all visible, ⌘A). Does nothing in year view. | () => void |
addEventFromRangeAdds 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 |
updateEventReplaces 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 |
editEventChanges 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 |
deleteEventDeletes 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 |
duplicateEventAdds 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 |
copyEventKeeps a copy of the event for pasteEvent. Changes no event. | (eventId: string) => void |
cutEventKeeps a copy of the event for pasteEvent, then deletes it. Undoable. | (eventId: string) => void |
pasteEventAdds 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 |
undoUndoes 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 |
redoDoes again the latest step undo took back. | () => void |
canUndoWhether 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 |
canRedoWhether redo has a step to do again. Any new change clears them. | boolean |
toggleWeekendsShows 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 |
toggleDeclinedEventsShows or hides the events you declined (see isDeclinedByViewer). Hiding them clears the selection when the selected event is one. | () => void |
toggleWeekNumbersShows or hides week numbers. | () => void |
showDayOpens the week containing date and briefly highlights that day. | (date: Date) => void |
navigateToDateShows 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 |
addEventAtNextSlotStarts 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.
| Field | Type |
|---|---|
snapMinutesSnap step in minutes. | number |
defaultEventDurationLength in minutes of a double-clicked event. | number |
dayStartHourFirst visible hour, normalized to 0–23. | number |
dayEndHourLast visible hour, normalized to after dayStartHour and at most 24. | number |
hourCycleClock style. | 12 | 24 |
localedate-fns locale. | Locale |
secondaryTimeZoneIANA id of the first additional time zone column, or undefined when there is none. | string | undefined |
secondaryTimeZonesIANA ids of the additional time zone columns, left to right, without zones the runtime doesn't know. | string[] |
timeZoneIANA 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 |
weekStartsOnFirst day of the week, for date pickers. Unset outside a provider, where the locale's applies. | 0 | 1 | 2 | 3 | 4 | 5 | 6 |
calendarsCalendars 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[] |
contactsPeople the participants field suggests. | EventContact[] |
roomsMeeting rooms the participants field offers. | EventRoom[] |
conferenceProvidersVideo call services the details offer. | ConferenceProviderOption[] |
locationSuggestionsPlaces 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.
| Field | Type |
|---|---|
contactsThe provider's contacts: the people you can add. | EventContact[] |
meetWithEmails of the people you're meeting with, in the order added. | string[] |
teammatesEmails of the teammates whose calendars show. | string[] |
shownPeopleEveryone whose events are drawn: the people you meet with, then the teammates not among them, each with the color their events take. | CalendarPerson[] |
addMeetWithAdds someone to the meeting. | (email: string) => void |
removeMeetWithTakes someone out of the meeting. | (email: string) => void |
clearMeetWithEnds the meeting: nobody is met with anymore. | () => void |
addTeammateShows a teammate's calendar. | (email: string) => void |
removeTeammateHides a teammate's calendar again. | (email: string) => void |
getPersonEventsA person's events from contactEvents, or an empty list when it has none for them. | (email: string) => DetailedCalendarEvent[] |
workingHoursThe 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.
| Field | Type |
|---|---|
noticeThe notice to show now, or null. | CalendarNotice | null |
showNoticeShows 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 |
dismissNoticeCloses the notice with this id. Does nothing once a newer one replaced it. | (id: number) => void |
CalendarNotice
| Field | Type |
|---|---|
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 |
titleThe second line: an event's title, which Calendar Toaster shows in curly quotes. | string |
onUndoTakes 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.
| Field | Type |
|---|---|
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 |
isAllDayDraws the event in the all-day row. Timed events that cross midnight go there too. | boolean |
colorThe 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.
| Field | Type |
|---|---|
eventThe event, with its in-progress start and end while it's dragged or resized. | TEvent |
viewView the event is drawn in. | "day" | "week" | "month" | "agenda" | "year" |
placementWhere the event is drawn, which sets how much room it has. | "time-grid" | "all-day" | "month-item" | "month-bar" | "agenda" |
isSelectedWhether the event is selected. | boolean |
isPastWhether the event has already ended. | boolean |
isDraggingWhether this is the copy that follows the pointer while dragging. | boolean |
isResizingWhether the event is being resized. | boolean |
isCompactWhether there's room for one line only: hour-grid blocks under 40px tall, and always in the all-day row and month view. | boolean |
timeLabelTime 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.
| Field | Type |
|---|---|
startStart, snapped to snapMinutes. For whole days, midnight that starts the first day. | Date |
endEnd: 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 |
isAllDaySet 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.
| Field | Type |
|---|---|
startMidnight that starts the first visible day. | Date |
endMidnight after the last visible day (exclusive). | Date |
CalendarInfo
An entry of the calendars prop.
| Field | Type |
|---|---|
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 |
emailAccount the calendar belongs to. The picker and the menu group calendars by it, and a moved event's calendarEmail becomes it. | string |
defaultRemindersReminders 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.
| Helper | Type |
|---|---|
resolveEventColorThe 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 |
moveEventToCalendarThe 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 |
groupCalendarsByEmailCalendars grouped by account email ({ email?, calendars }), in the order given. | (calendars) => CalendarGroup[] |
addReminderThe 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[] |
getReminderMinutesMinutes 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 |
isSameReminderWhether 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.
| Helper | Type |
|---|---|
expandRecurringEventsWhat 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[] |
findEventOrOccurrenceThe 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 |
applyRecurringEditThe 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 |
findEventSeriesThe 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 |
getSeriesEditScopesThe 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[] |
getSeriesDeleteScopesThe options for deleting a date: ["this", "all"] on the first date, else all three. | (events, event) => SeriesEditScope[] |
getSeriesEditChangesWhat 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 |
getSeriesDeleteChangesWhat deleting a date with an option changes, in the same order. | (options: SeriesDeleteOptions) => EventHistoryChange[] |
EventContact
An entry of the contacts prop.
| Field | Type |
|---|---|
email (required)Address, the participant's identity once invited. | string |
nameDisplay name. Defaults to the email. | string |
recentListed on focus, before typing, with a history icon, as a recently invited contact. | boolean |
colorColor 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).
| Field | Type |
|---|---|
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.
| Field | Type |
|---|---|
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 |
icon16px icon in the menu and on the event. Defaults to a camera. | React.ReactNode |
hintMuted 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.
| Field | Type |
|---|---|
name (required)Name of the place, e.g. "Central Park". | string |
addressShown under the name, and saved after it: "Central Park, New York, NY, USA". | string |