RegistryInstall CalendarCN with the shadcn CLI

Components

Event Details

The panel and popover for viewing and editing an event.

EventDetailPanel shows an event's details and edits them in place. The views open it in a popover beside the selected event, and you can render it yourself anywhere, such as a side panel. It needs an event, and onEventChange to edit it: without a change handler the panel is read-only. Inside a CalendarProvider it uses the provider's clock and locale, and its calendars, contacts, rooms, conferenceProviders and locationSuggestions. On its own it uses the defaults: no calendars to pick, contacts, rooms, conferencing services or place suggestions. The preview passes the live demo's, from Sample Data and the conference providers.

Installation

pnpm dlx shadcn add @calendarcn/event-details

Usage

import { EventDetailPanel } from "@/components/event-detail-panel";

export function EventSidebar() {
  const [event, setEvent] = React.useState(initialEvent);

  return <EventDetailPanel event={event} onEventChange={setEvent} />;
}

To show the selected event of a calendar in a side panel, read it from useCalendar() and turn the popover off on the view. Pass onTitlePreview while the selected event is the draft, so typing its title previews it and the first edit saves it:

function SidePanel() {
  const { selectedEvent, eventDraft, editEvent, updateEventDraft } =
    useCalendar<DetailedCalendarEvent>();
  if (!selectedEvent) return null;

  return (
    <EventDetailPanel
      event={selectedEvent}
      onEventChange={editEvent}
      onTitlePreview={
        eventDraft?.id === selectedEvent.id ? updateEventDraft : undefined
      }
    />
  );
}

<CalendarProvider defaultEvents={events}>
  <WeekView showEventPopover={false} />
  <SidePanel />
</CalendarProvider>;

editEvent changes the event like the views' popover does: on a date of a repeating event, it holds the change until the event is left, then asks which events it applies to.

Leave out onEventChange to show an event read-only, for example one from a calendar people can only view. The title and the other fields don't accept typing and the menus that change the event are disabled, so no edit looks saved when it isn't.

<EventDetailPanel event={event} />

The "..." menu cuts, copies, duplicates and deletes the event through onCut, onCopy, onDuplicate and onDelete; an action you don't pass is disabled. The views' popover passes the provider's. For a panel you render yourself, pass useCalendar()'s:

const { cutEvent, copyEvent, duplicateEvent, deleteEvent } =
  useCalendar<DetailedCalendarEvent>();

<EventDetailPanel
  event={selectedEvent}
  onEventChange={editEvent}
  onCut={() => cutEvent(selectedEvent.id)}
  onCopy={() => copyEvent(selectedEvent.id)}
  onDuplicate={() => duplicateEvent(selectedEvent.id)}
  onDelete={() => deleteEvent(selectedEvent.id)}
/>;

The repeat row's arrows step through a series. In the views' popover they work on their own: the provider finds the selected event's neighbors (previousInSeries and nextInSeries from useCalendar(), null at the series' ends) and showSeriesOccurrence selects one and moves to it. Occurrences your events don't hold are generated from the rule, so stepping to one selects it without adding anything; its first edit stores it, through onEventCreate. Pass the same to a panel you render yourself:

const { previousInSeries, nextInSeries, showSeriesOccurrence } =
  useCalendar<DetailedCalendarEvent>();

<EventDetailPanel
  event={selectedEvent}
  onEventChange={editEvent}
  onPrevWeek={
    previousInSeries ? () => showSeriesOccurrence(previousInSeries) : undefined
  }
  onNextWeek={
    nextInSeries ? () => showSeriesOccurrence(nextInSeries) : undefined
  }
/>;

Outside a provider, findSeriesOccurrence(events, event, "next") (from @/lib/recurrence) finds the occurrence: { id, start, event }, with the event stored for that date or the one generated for it. A series is a repeating event plus the events that name it with seriesId; excludedDates are skipped. A recurrenceRule counts its days in the event's timeZone, so a 9 AM New York series stays at 9 AM there across daylight saving changes. Events whose recurrence is display text step between the events with the same title, calendar and text.

Conference providers

The Conferencing row adds a video call from the services in the provider's conferenceProviders. Nothing is on by default: with no services the row is hidden, unless the event already has a call. To offer the live demo's Google Meet, Zoom and Microsoft Teams, install them and pass them in:

pnpm dlx shadcn add @calendarcn/conference-providers
import { DEMO_CONFERENCE_PROVIDERS } from "@/lib/conference-providers";

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

Calendar takes the same prop.

They're placeholders. Each createConference makes up a call in the service's code format (abc-defg-hij for Meet) on example.com, after 400ms so the row's pending state shows, and no link opens a real meeting. Before people rely on them, make createConference create the meeting through the service's API and return its link. The API needs your credentials, so call it from your server:

import type { ConferenceProviderOption } from "@/components/calendar-types";

const conferenceProviders: ConferenceProviderOption[] = [
  {
    provider: "zoom",
    label: "Zoom",
    icon: <ZoomLogo />,
    createConference: async (event) => {
      // Your route creates the meeting with Zoom's API
      const response = await fetch("/api/zoom-meetings", {
        method: "POST",
        body: JSON.stringify({ title: event.title, start: event.start }),
      });
      if (!response.ok) throw new Error("Zoom didn't create the meeting");
      const meeting = await response.json();
      return { provider: "zoom", url: meeting.joinUrl, meetingId: meeting.id };
    },
  },
];

A rejected promise adds no call. Labels must be unique, so you can offer one service twice, like two Zoom accounts.

Logos

Google Meet, Zoom and Microsoft Teams logos are their owners' trademarks, so the item ships none and the row shows a camera for each service. To look like the live demo, give each option your own logo as its icon, taken from the service's brand resources and used under its terms. The icon shows at 16px in the menu and on the event. The demo does it this way:

import type { ConferenceProvider } from "@/components/calendar-types";
import { DEMO_CONFERENCE_PROVIDERS } from "@/lib/conference-providers";

// Your own logo components or images
import { GoogleMeetLogo, TeamsLogo, ZoomLogo } from "@/components/logos";

const LOGOS: Partial<Record<ConferenceProvider, React.ReactNode>> = {
  "google-meet": <GoogleMeetLogo />,
  zoom: <ZoomLogo />,
  "microsoft-teams": <TeamsLogo />,
};

const conferenceProviders = DEMO_CONFERENCE_PROVIDERS.map((option) => ({
  ...option,
  icon: LOGOS[option.provider],
}));

An image file works too: icon: <img src="/logos/zoom.svg" alt="" className="size-4" />. An event's call shows the icon of the option that created it (the one with its label), or of the first option of its provider, so the demo's events that already have a Meet call show your Meet logo too.

Features

  • Edit the title in place. With onEventChange wired to the calendar, the event updates as you type.
  • Pick the start and end times from a menu in 15-minute steps. End times show how long the event lasts (1h 30min).
  • Type a time and the menu lists what it can mean, daytime first: 7 gives 7 PM, then 7 AM. In the end field a number is also a duration: 45 gives 45 minutes later.
  • Hovering a time previews it. Enter, a click, or leaving the field after typing or arrow keys saves it. Esc restores the old value.
  • Pick dates from a date picker, or type one (Nov 12). From the input, ↑ and ↓ move a day, and Page Up and Page Down a month.
  • Switch an event to all-day and back: it gets its own times back, or 9–10 AM when it had none.
  • Time options follow the wall clock, so they stay right on the days daylight saving time starts and ends.
  • In every menu and list of the details, Esc closes it and restores the value from before it opened. Arrow keys and the pointer only preview: the time zone list shows the highlighted city in the field until Enter or a click picks it.
  • Pick the event's time zone from a searchable list of every zone, with recent and popular ones first. The times keep their wall-clock value in the new zone, so the event moves on the grid, which (like the panel's times) stays in the calendar's zone, the viewer's unless the provider sets timeZone: 2 PM in New York becomes 2 PM in Tokyo, which is 1 AM New York time.
  • When the calendar draws in another zone than the event's (the provider's timeZone, or while travelling), the times read on the calendar's clock and the time zone row shows the calendar's zone, as in Notion Calendar. "Switch to event's time zone to edit" shows the times on the event's own clock and lets you change its zone; "Switch to your primary time zone" goes back.
  • Set a repeat rule from Notion's presets or the custom dialog (every N days, weeks, months or years, on chosen days, on the 1st to 4th or last weekday of the month, until a date or N times). .ics import and export keep it as an RRULE; an RRULE the details can't show reads "Custom repeat".
  • Change or delete one date of a repeating event and the calendar asks which events it applies to, as Notion Calendar does. Changes made in the details wait, marked with a dot, until you leave the event. See Editing a repeating event.
  • Fields the event doesn't set (participants, AI meeting notes, location, links, description, reminders) show Notion's muted placeholders. So does conferencing when the provider passes conferenceProviders; without them the row is hidden, unless the event already has a call.
  • Invite participants. Focusing the field lists the provider's recent contacts; typing filters them and offers a typed email address. The calendar's account (calendarEmail) joins as the organizer with the first guest, and stays while anyone is invited. Each guest shows their response (accepted, declined or maybe) and "Organizer" or "Optional"; hover a guest to copy their email, email them, mark them optional or remove them. Esc closes the list and never invites anyone.
  • Book meeting rooms from the provider's rooms, under "View rooms and resources" or by typing a room's name.
  • Add a video call from one of the provider's conferenceProviders. While an async createConference runs, the row shows the service as pending; then it shows the service's icon, name (a link that joins the call) and meeting code, with buttons to copy the link and to switch service or remove the call.
  • Type a location: the typed text is listed first, then the matching locationSuggestions. A location that's a web address opens itself. Any other location links to a Google Maps search, so clicking it sends the location text to Google.
  • Turn AI meeting notes on or off. This only sets the event's aiMeetingNotes flag: the panel doesn't record or write notes.
  • Add a link from "Add links and attachments": paste or type an address and press Enter. A bare domain like example.com gets https://, and text that isn't a link is dropped. Hover a link, or Tab onto it, to see its address with a copy button.
  • Attach a file from the same menu. The panel keeps its name, size and type with a blob: URL; nothing is uploaded.
  • Edit the description in place: the event takes the text when you leave it, and Esc restores it. Web addresses in it become links, and are also listed after the event's links.
  • Move the event to another of the provider's calendars (grouped by account) or give it its own color, set it busy or free and pick who can see it, from menus that open beside the panel. Hovering a choice previews it; Esc closes the menu and keeps the old value.
  • Add reminders from presets, or type a number to get it in minutes, hours, days or weeks ("2h", "10 mins"), up to 4 weeks before. Reminders stay sorted, and one that fires with another ("60min" and "1hour") isn't added twice. Adding one closes the list, and typing opens it again. Hover a reminder to remove it.
  • Right-click an event on the calendar to change its color or calendar, or to cut, copy, duplicate or delete it. The details' "..." menu has the same four actions, each with its key: see Keyboard shortcuts.

Custom details

Pass renderEventDetails to CalendarProvider to replace the popover's body. It gets the selected event, a close function and isNew, which is true right after the event was created, so you can focus its title. A new event is a draft until its first edit: updateEvent() from useCalendar() saves it, and updateEventDraft() previews a change without saving. See Creating events. Render a component from it when you need hooks: useCalendar() to save edits, useCalendarConfig() to format times like the calendar does.

Change events with editEvent from useCalendar() rather than updateEvent: on a date of a repeating event it holds each change until the event is left, then asks once, as the built-in details do. The example above does that for the title and the color.

Build your own panel

EventDetailPanel is one component per section, and they install with it. Render the ones you need, in your own order, to build a smaller panel or a different layout. Each section takes EventDetailSectionProps: the event, and onEventChange, without which the section is read-only.

import type { EventDetailSectionProps } from "@/components/calendar-types";
import { EventDetailParticipants } from "@/components/event-detail-participants";
import {
  EventDetailDivider,
  EventDetailGroup,
} from "@/components/event-detail-parts";
import { EventDetailTime } from "@/components/event-detail-time";

export function CompactDetails({
  event,
  onEventChange,
}: EventDetailSectionProps) {
  return (
    <div className="flex flex-col text-sm font-medium">
      <EventDetailGroup name="when">
        <EventDetailTime event={event} onEventChange={onEventChange} />
      </EventDetailGroup>
      <EventDetailDivider />
      <EventDetailGroup name="who">
        <EventDetailParticipants event={event} onEventChange={onEventChange} />
      </EventDetailGroup>
    </div>
  );
}
Import fromExportsWhat it is
@/components/event-detail-timeEventDetailTime, EventDetailAllDayStart and end times and dates; the all-day switch.
@/components/event-detail-time-fieldEventDetailTimeFieldA time field with the floating time menu: typed times, durations, hover previews, and Esc restores. EventDetailTime renders two.
@/components/event-detail-date-fieldEventDetailDateFieldA date field with the date picker; minDate turns off earlier days.
@/components/event-detail-timezoneEventDetailTimezoneThe time zone.
@/components/event-detail-recurrenceEventDetailRecurrenceThe repeat rule, with arrows that step through the series when it repeats: onPrevious and onNext show the neighbors (previousInSeries / nextInSeries); leave one out to disable its arrow.
@/components/event-detail-participantsEventDetailParticipantsGuests and rooms.
@/components/event-detail-conferencingEventDetailConferencingThe video call.
@/components/event-detail-ai-notesEventDetailAiNotesWhether AI meeting notes are on.
@/components/event-detail-locationEventDetailLocationThe location.
@/components/event-detail-linksEventDetailLinksLinks and attached files.
@/components/event-detail-descriptionEventDetailDescriptionThe description.
@/components/event-detail-calendarEventDetailCalendarThe calendar and its color.
@/components/event-detail-availabilityEventDetailAvailabilityBusy or free, and visibility.
@/components/event-detail-remindersEventDetailRemindersReminders.
@/components/event-detail-partsEventDetailGroup, EventDetailDivider, EventDetailSection, EventDetailRow, EventDetailPlaceholderRow, EventDetailTooltipLayout: groups of sections between dividers, rows on the panel's icon column, Notion's muted placeholder row, and the hover tooltip.
@/components/event-detail-partsEVENT_DETAIL_*_CLASS, PANEL_*_CLASS, ROW_BOX_CLASSThe panel's colors and the styles of its inputs, rows and menus, in light and dark.
@/components/event-detail-partscloseMenuOnEscape, stopEscapePropagation, getPanelMenuSideOffset, getEventDetailPortalContainerMenu helpers: Esc closes a menu without deselecting the event, menus line up with the panel's edge, and lists portal into the dialog around the panel, if any.
@/components/event-detail-suggestionsEventDetailSuggestions, EventDetailSuggestion, HighlightedMatch, handleSuggestionKeyThe floating list a combobox field shows while typing (the participants' contacts, the location's places), its options, the matched text kept bright, and its arrow keys and Enter.
@/hooks/use-inline-edituseInlineEditA text field that edits in place: Enter or blur commits, Esc restores the value from before, and onCommit can reject a value by returning null.
@/hooks/use-hover-tooltipuseHoverTooltipOpen state for a tooltip that shows after the pointer rests on its trigger and stays while the pointer moves onto it.
@/hooks/use-field-popoveruseFieldPopoverFocus, blur and Esc for a field whose menu or picker keeps focus in its input.
@/lib/time-inputgetStartTimeOptions, getEndTimeOptions, matchStartTimes, matchEndTimes, formatDuration, parseDateInputThe time menu's options on the wall clock, the times and durations typed text can mean, and typed dates.

API Reference

EventDetailPanel

TEvent extends DetailedCalendarEvent. Edits keep your other fields.

PropType
event (required)
The event to show.
TEvent
onEventChange
Called with the edited event: on every keystroke in the title, and when a time, date or option is committed. Without it the panel is read-only: nothing accepts typing and the menus that change the event are disabled.
(event: TEvent) => void
headerActions
Extra buttons in the header row, after the "..." menu.
ReactNode
onTitlePreview
Set while the event is a draft that isn't stored yet, like eventDraft from useCalendar(). Called on every keystroke in the title instead of onEventChange, which then saves the draft: on Enter in a title, when focus leaves a title that changed, or on any other field's first edit. Escape takes the title back and saves nothing. Hides the "..." menu.
(event: TEvent) => void
autoFocusTitle
Focuses and selects the title once, e.g. for a just-created event.
boolean
onTitleAutoFocused
Called after the title was auto-focused, so the request isn't repeated.
() => void
onPrevWeek
Shows the previous event of a repeating series (the repeat row's ‹). Leave it out at the start of the series to disable the arrow. The views' popover passes the provider's previousInSeries.
() => void
onNextWeek
Shows the next event of a repeating series (the repeat row's ›). Leave it out at the end of the series to disable the arrow. The views' popover passes the provider's nextInSeries.
() => void
onCut
The "..." menu's Cut (⌘X): keeps a copy of the event for pasting and deletes it. The item is disabled without it. The views' popover passes the provider's cutEvent.
() => void
onCopy
The "..." menu's Copy (⌘C): keeps a copy of the event for pasting. The item is disabled without it. The views' popover passes the provider's copyEvent.
() => void
onDuplicate
The "..." menu's Duplicate (⌘D): adds a copy at the same time and selects it. The item is disabled without it. The views' popover passes the provider's duplicateEvent.
() => void
onDelete
The "..." menu's Delete (delete): deletes the event. The item is disabled without it. The views' popover passes the provider's deleteEvent.
() => void

EventDetailsRenderProps

Passed to renderEventDetails on CalendarProvider.

FieldType
event
The selected event.
TEvent
close
Closes the popover by clearing the selection.
() => void
isNew
Whether the event was just created, as a draft or by addEventFromRange, so its title should be focused. True on the first render after creation only.
boolean

DetailedCalendarEvent

CalendarEvent plus the Notion Calendar-style details the panel reads and edits. Every field is optional.

FieldType
kind
Kind picked in the header menu. Defaults to "event".
"event" | "focus-time" | "out-of-office" | "birthday"
calendarId
Calendar the event belongs to, an id from the provider's calendars. Without its own color, the event is drawn in this calendar's.
string
calendarEmail
Account email shown when calendarId isn't one of the provider's calendars. Moving the event sets it to the new calendar's email.
string
description
Free-text notes.
string
location
Where it happens.
string
timeZone
IANA time zone, e.g. "America/Sao_Paulo", shown as "GMT−3 Sao Paulo". Defaults to the viewer's zone. Picking another zone in the details keeps the event's wall-clock time.
string
timezone
Deprecated: a time zone label, e.g. "GMT-3 Sao Paulo", shown when timeZone is not set.
string
recurrenceRule
Repeat rule, see [RecurrenceRule](#recurrencerule). Read as "Every 2 weeks on Mon, Thu". Takes precedence over recurrence; .ics import fills it and export writes it as an RRULE.
RecurrenceRule
recurrence
Repeat rule as display text, e.g. "Every week on Thu", or an RRULE .ics import couldn't fit in recurrenceRule (it reads "Custom repeat"). Used when recurrenceRule is not set.
string
excludedDates
Dates a repeating event skips, each the start of an occurrence (RFC 5545 EXDATE). .ics import and export read and write it.
Date[]
seriesId
On an occurrence of a repeating event: the series' event id. Generated occurrences carry it, and an edited one is stored with it.
string
originalStart
On an occurrence: its start in the series before any edit (RFC 5545 RECURRENCE-ID), so an edited occurrence replaces the right date.
Date
participants
Guests: email, name, response (accepted, declined, tentative, needs-action), organizer, optional, and self on the viewer, whose "declined" makes the event declined.
EventParticipant[]
rooms
Meeting rooms: id, name, location, capacity, response.
EventRoom[]
conference
Video call: provider ("google-meet", "zoom", "microsoft-teams" or "other"), url, meetingId, and label, the name of the conferenceProviders option that created it.
EventConference
aiMeetingNotes
Whether AI meeting notes are taken.
boolean
links
Links attached to the event, shown by title when set. Only http: and https: addresses open; others, like javascript: or data:, show as text.
{ url: string; title?: string }[]
attachments
Files attached to the event (size in bytes, MIME type). A url opens only when it's http:, https: or blob:; javascript: and data: show as text. A file attached in the panel gets a blob: URL that stops working when the page reloads. The panel revokes it when the file is removed; otherwise upload the file or revoke the URL yourself (URL.revokeObjectURL), e.g. when the event is deleted.
{ name: string; url: string; size?: number; type?: string }[]
reminders
Reminders before the event. time is the time of day for all-day events ("1 day before at 9 AM").
{ amount: number; unit: "minutes" | "hours" | "days" | "weeks"; time?: { hours: number; minutes: number } }[]
status
Busy or free.
"busy" | "free"
visibility
Visibility setting.
"default" | "public" | "private"

RecurrenceRule

The structured repeat rule in recurrenceRule: the part of an RFC 5545 RRULE the repeat row edits. Days are counted in the event's timeZone, from the series' first event, which always counts as the first occurrence. An all-day series counts whole days in the viewer's calendar.

FieldTypeDefault
frequency (required)
How often it repeats (RRULE FREQ).
"daily" | "weekly" | "monthly" | "yearly"–
interval
Repeats every interval days, weeks, months or years (INTERVAL).
number1
weekdays
Days a weekly rule falls on, 0 for Sunday (BYDAY=MO,TH). Defaults to the start's weekday. Monday to Friday reads as "Every weekday", Saturday and Sunday as "Every weekend day".
(0 | 1 | 2 | 3 | 4 | 5 | 6)[]–
monthlyBy
What a monthly rule repeats on: the start's day of the month ("on the 6th"; months without it, like the 31st in April, are skipped) or its weekday in the month ("on the 1st Sat").
"day-of-month" | "weekday-of-month""day-of-month"
weekOfMonth
Which of the month's weekdays a "weekday-of-month" rule falls on: the 1st to 4th, or -1 for the last ("on the last Sat", BYDAY=-1SA). Defaults to the start's position in its month, the last for a fifth one. Set -1 to keep "the last Sat" when the start is also the 4th.
1 | 2 | 3 | 4 | -1–
weekStartsOn
Day the weeks of a weekly rule start on (WKST), which decides the weeks an "every 2 weeks" rule skips. Defaults to Monday, as in RFC 5545; independent of the calendar's weekStartsOn.
0 | 1 | 2 | 3 | 4 | 5 | 61
end
When the series stops, see [RecurrenceEnd](#recurrenceend).
RecurrenceEnd{ type: "never" }

RecurrenceEnd

When a repeating event stops, by its type:

typeType
"never"
Repeats forever.
{ type: "never" }
"on"
Stops after the day of date, inclusive, a day in the event's time zone. Reads as "until Dec 6". .ics export writes an UNTIL at the end of that day (a date for all-day events).
{ type: "on"; date: Date }
"after"
Stops after count occurrences, the first included. Reads as "for 7 times" (COUNT).
{ type: "after"; count: number }

On this page