# Calendar Core

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

Live example, interactive at https://calendarcn.xyz/docs/components/calendar-core. Its source:

```tsx title="src/examples/controlled-events-demo.tsx"
"use client";

import * as React from "react";
import { format, isSameDay } from "date-fns";

import { cn } from "@/lib/utils";
import { CalendarProvider, useCalendar } from "@/components/calendar-provider";
import { WeekView } from "@/components/week-view";
import { Button } from "@/components/ui/button";
import type {
  DetailedCalendarEvent,
  EventColor,
} from "@/components/calendar-types";
import { createSampleEvents } from "@/lib/sample-events";

/** Swatch class per event color, from the `--event-*-border` theme tokens */
const SWATCH_CLASS: Record<EventColor, string> = {
  red: "bg-event-red-border",
  orange: "bg-event-orange-border",
  yellow: "bg-event-yellow-border",
  green: "bg-event-green-border",
  blue: "bg-event-blue-border",
  purple: "bg-event-purple-border",
  gray: "bg-event-gray-border",
};

export function ControlledEventsDemo() {
  // Your app owns the events: the calendar reports every change through
  // `onEventsChange` and draws whatever `events` holds
  const [events, setEvents] = React.useState<DetailedCalendarEvent[]>(() =>
    createSampleEvents(new Date()),
  );

  return (
    <CalendarProvider events={events} onEventsChange={setEvents}>
      {/* The list sits beside the calendar when there's room, below it otherwise */}
      <div className="@container h-full">
        <div className="flex h-full flex-col @2xl:flex-row">
          <div className="min-h-0 min-w-0 flex-1">
            <WeekView scrollToHour={8} />
          </div>
          <EventList
            events={events}
            onReset={() => setEvents(createSampleEvents(new Date()))}
          />
        </div>
      </div>
    </CalendarProvider>
  );
}

interface EventListProps {
  events: DetailedCalendarEvent[];
  onReset: () => void;
}

/** The app's copy of the events, updated live as you drag, resize or create */
function EventList({ events, onReset }: EventListProps) {
  const { selectedEventId, selectEvent } = useCalendar();
  const sortedEvents = React.useMemo(
    () => [...events].sort((a, b) => a.start.getTime() - b.start.getTime()),
    [events],
  );

  return (
    <aside className="flex h-40 shrink-0 flex-col border-t @2xl:h-auto @2xl:w-56 @2xl:border-t-0 @2xl:border-l">
      <div className="flex items-center justify-between gap-2 border-b px-3 py-2">
        <h3 className="text-xs font-medium">
          Events{" "}
          <span className="text-muted-foreground tabular-nums">
            ({events.length})
          </span>
        </h3>
        <Button variant="ghost" size="sm" className="h-7" onClick={onReset}>
          Reset
        </Button>
      </div>
      <ul className="flex-1 overflow-y-auto p-1">
        {sortedEvents.map((event) => (
          <li key={event.id}>
            <button
              type="button"
              onClick={() => selectEvent(event.id)}
              className={cn(
                "flex w-full items-start gap-2 rounded-sm px-2 py-1.5 text-left transition-colors duration-150 ease-out outline-none hover:bg-accent focus-visible:ring-[3px] focus-visible:ring-ring/50",
                event.id === selectedEventId && "bg-accent",
              )}
            >
              <span
                aria-hidden
                className={cn(
                  "mt-1 size-2 shrink-0 rounded-full",
                  SWATCH_CLASS[event.color ?? "blue"],
                )}
              />
              <span className="min-w-0">
                <span className="block truncate text-xs font-medium">
                  {event.title}
                </span>
                <span className="block text-[11px] text-muted-foreground tabular-nums">
                  {formatEventTime(event)}
                </span>
              </span>
            </button>
          </li>
        ))}
      </ul>
    </aside>
  );
}

/** "Mon 9:00 AM – 9:30 AM", "Fri 4:00 PM – Sat 1:00 PM" or "Wed – Thu, all day" */
function formatEventTime(event: DetailedCalendarEvent): string {
  if (event.isAllDay) {
    const startDay = format(event.start, "EEE");
    const endDay = format(event.end, "EEE");
    if (startDay === endDay) {
      return `${startDay}, all day`;
    }
    return `${startDay} – ${endDay}, all day`;
  }

  const endFormat = isSameDay(event.start, event.end) ? "p" : "EEE p";
  return `${format(event.start, "EEE p")} – ${format(event.end, endFormat)}`;
}
```

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

```bash
npx shadcn add @calendarcn/calendar-core
```

Or install it by hand:

1. Install the dependencies: `npm install date-fns`
2. Copy these files into your project, keeping the paths under your components, hooks and lib folders:
   - [`components/calendar-types.ts`](https://github.com/vmnog/calendarcn/blob/main/src/components/calendar-types.ts)
   - [`components/week-view-types.ts`](https://github.com/vmnog/calendarcn/blob/main/src/components/week-view-types.ts)
   - [`components/calendar-provider.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/calendar-provider.tsx)
   - [`components/scheduling-provider.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/scheduling-provider.tsx)
   - [`components/calendar-popover-context.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/calendar-popover-context.tsx)
   - [`components/event-title-focus-context.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/event-title-focus-context.tsx)
   - [`components/calendar-loading-bar.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/calendar-loading-bar.tsx)
   - [`components/calendar-people.tsx`](https://github.com/vmnog/calendarcn/blob/main/src/components/calendar-people.tsx)
   - [`hooks/use-calendar-shortcuts.ts`](https://github.com/vmnog/calendarcn/blob/main/src/hooks/use-calendar-shortcuts.ts)
   - [`hooks/use-controllable-state.ts`](https://github.com/vmnog/calendarcn/blob/main/src/hooks/use-controllable-state.ts)
   - [`hooks/use-day-range-draw.ts`](https://github.com/vmnog/calendarcn/blob/main/src/hooks/use-day-range-draw.ts)
   - [`hooks/use-double-click.ts`](https://github.com/vmnog/calendarcn/blob/main/src/hooks/use-double-click.ts)
   - [`hooks/use-event-keyboard.ts`](https://github.com/vmnog/calendarcn/blob/main/src/hooks/use-event-keyboard.ts)
   - [`hooks/use-now.ts`](https://github.com/vmnog/calendarcn/blob/main/src/hooks/use-now.ts)
   - [`hooks/use-pointer-gesture.ts`](https://github.com/vmnog/calendarcn/blob/main/src/hooks/use-pointer-gesture.ts)
   - [`hooks/use-timezone-label.ts`](https://github.com/vmnog/calendarcn/blob/main/src/hooks/use-timezone-label.ts)
   - [`lib/event-utils.ts`](https://github.com/vmnog/calendarcn/blob/main/src/lib/event-utils.ts)
   - [`lib/timezone-label.ts`](https://github.com/vmnog/calendarcn/blob/main/src/lib/timezone-label.ts)
   - [`lib/recurrence.ts`](https://github.com/vmnog/calendarcn/blob/main/src/lib/recurrence.ts)
   - [`lib/time-zones.ts`](https://github.com/vmnog/calendarcn/blob/main/src/lib/time-zones.ts)
   - [`lib/event-history.ts`](https://github.com/vmnog/calendarcn/blob/main/src/lib/event-history.ts)
   - [`lib/event-selection.ts`](https://github.com/vmnog/calendarcn/blob/main/src/lib/event-selection.ts)
   - [`lib/free-busy.ts`](https://github.com/vmnog/calendarcn/blob/main/src/lib/free-busy.ts)
   - [`lib/people.ts`](https://github.com/vmnog/calendarcn/blob/main/src/lib/people.ts)
   - [`lib/keyboard-shortcuts.ts`](https://github.com/vmnog/calendarcn/blob/main/src/lib/keyboard-shortcuts.ts)
   - [`lib/availability.ts`](https://github.com/vmnog/calendarcn/blob/main/src/lib/availability.ts)

## Usage

```tsx
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.

```tsx
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](#repeating-events). To fetch events for the dates on screen as people navigate, use `onVisibleRangeChange` and `loading`: see [Loading Events](/docs/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](/docs/components/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](#undo-and-redo). 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.

```tsx
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](#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](/docs/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](/docs/components/calendar-header#calendarviewswitcher) and the [Command Menu](/docs/components/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](/docs/components/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`).

```tsx
// 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

Live example, interactive at https://calendarcn.xyz/docs/components/calendar-core. Its source:

```tsx title="src/examples/config-demo.tsx"
"use client";

import * as React from "react";
import { ptBR } from "date-fns/locale";

import { CalendarProvider } from "@/components/calendar-provider";
import { WeekView } from "@/components/week-view";
import type { WeekStartsOn } from "@/components/calendar-types";
import { createSampleEvents } from "@/lib/sample-events";

/** Weeks start on Monday */
const WEEK_STARTS_ON: WeekStartsOn = 1;

export function ConfigDemo() {
  // The provider reads its initial events once, so create them once
  const [initialEvents] = React.useState(() =>
    createSampleEvents(new Date(), WEEK_STARTS_ON),
  );

  return (
    <CalendarProvider
      defaultEvents={initialEvents}
      // 24-hour clock: "15:00" instead of "3 PM"
      hourCycle={24}
      // Day and month names, dates and week numbers in Portuguese
      locale={ptBR}
      weekStartsOn={WEEK_STARTS_ON}
      // Only working hours: the grid runs from 08:00 to 20:00
      dayStartHour={8}
      dayEndHour={20}
      // Drag, resize and new events move in 30-minute steps
      snapMinutes={30}
    >
      <WeekView />
    </CalendarProvider>
  );
}
```

Display and interaction settings are plain props: a 24-hour clock, a [date-fns locale](https://date-fns.org/docs/I18n) 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

Live example, interactive at https://calendarcn.xyz/docs/components/calendar-core. Its source:

```tsx title="src/examples/time-zone-demo.tsx"
"use client";

import * as React from "react";
import { format } from "date-fns";

import { useToday } from "@/hooks/use-now";
import { Calendar } from "@/components/calendar";
import type { DetailedCalendarEvent } from "@/components/calendar-types";
import { fromZonedWallClock, getZonedNow } from "@/lib/time-zones";

/** The office the calendar is drawn for */
const TIME_ZONE = "Asia/Tokyo";

/** Where the office's other team works: its hours show beside Tokyo's */
const SECOND_TIME_ZONES = ["Asia/Kolkata"];

/**
 * The instant a clock in Tokyo reads `hour`:`minute`, `dayOffset` days from
 * today in Tokyo: what your app stores for a time set there
 */
function inTokyo(dayOffset: number, hour: number, minute = 0): Date {
  const today = getZonedNow(TIME_ZONE);
  return fromZonedWallClock(
    new Date(
      today.getFullYear(),
      today.getMonth(),
      today.getDate() + dayOffset,
      hour,
      minute,
    ),
    TIME_ZONE,
  );
}

/** Two meetings today in Tokyo, lunch tomorrow, an offsite the day after */
function createOfficeEvents(): DetailedCalendarEvent[] {
  const today = getZonedNow(TIME_ZONE);
  // All-day events are calendar dates, not instants: a local midnight
  const offsiteDay = new Date(
    today.getFullYear(),
    today.getMonth(),
    today.getDate() + 2,
  );
  return [
    {
      id: "standup",
      title: "Team standup",
      start: inTokyo(0, 10),
      end: inTokyo(0, 10, 30),
      color: "blue",
      timeZone: TIME_ZONE,
    },
    {
      id: "bangalore-call",
      title: "Call with Bangalore",
      start: inTokyo(0, 14),
      end: inTokyo(0, 15),
      color: "purple",
      timeZone: TIME_ZONE,
    },
    {
      id: "lunch",
      title: "Lunch with Kenji",
      start: inTokyo(1, 12),
      end: inTokyo(1, 13),
      color: "orange",
      timeZone: TIME_ZONE,
    },
    {
      id: "offsite",
      title: "Offsite",
      start: offsiteDay,
      end: offsiteDay,
      isAllDay: true,
      color: "green",
    },
  ];
}

export function TimeZoneDemo() {
  // Your app keeps instants. The calendar draws them on Tokyo's clock and
  // reports every change as instants again.
  const [events, setEvents] = React.useState(createOfficeEvents);

  return (
    // The list sits beside the calendar when there's room, below it otherwise
    <div className="@container h-full">
      <div className="flex h-full flex-col @2xl:flex-row">
        <div className="min-h-0 min-w-0 flex-1">
          <Calendar
            events={events}
            onEventsChange={setEvents}
            // Owned by the calendar, so the time zone labels can change them
            defaultTimeZone={TIME_ZONE}
            defaultSecondaryTimeZones={SECOND_TIME_ZONES}
            // The week number beside the title follows the zone's week too
            defaultViewSettings={{ showWeekNumbers: true }}
            // Other examples share this page: leave the keys to it
            shortcuts={false}
          />
        </div>
        <YourClock events={events} />
      </div>
    </div>
  );
}

interface YourClockProps {
  events: DetailedCalendarEvent[];
}

/** The app's events as it stores them, read on the viewer's own clock */
function YourClock({ events }: YourClockProps) {
  // The server doesn't know your clock: list nothing until hydration ends
  const today = useToday();
  const sortedEvents = React.useMemo(
    () => [...events].sort((a, b) => a.start.getTime() - b.start.getTime()),
    [events],
  );

  if (!today) return null;

  return (
    <aside className="flex h-40 shrink-0 flex-col border-t @2xl:h-auto @2xl:w-56 @2xl:border-t-0 @2xl:border-l">
      <h3 className="border-b px-3 py-2 text-xs font-medium">Your clock</h3>
      <ul
        aria-label="Your clock"
        className="flex-1 overflow-y-auto p-2 text-xs tabular-nums"
      >
        {sortedEvents.map((event) => (
          <li key={event.id} className="py-1">
            {event.title}, {formatOnYourClock(event)}
          </li>
        ))}
      </ul>
    </aside>
  );
}

/** "Sat 9:00 PM", or "Tue, all day" */
function formatOnYourClock(event: DetailedCalendarEvent): string {
  if (event.isAllDay) return `${format(event.start, "EEE")}, all day`;
  return format(event.start, "EEE p");
}
```

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.

```tsx
<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 `Date`s 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

Live example, interactive at https://calendarcn.xyz/docs/components/calendar-core. Its source:

```tsx title="src/examples/secondary-time-zone-demo.tsx"
"use client";

import * as React from "react";

import { CalendarProvider } from "@/components/calendar-provider";
import { WeekView } from "@/components/week-view";
import { createSampleEvents } from "@/lib/sample-events";

export function SecondaryTimeZoneDemo() {
  // The provider reads its initial events once, so create them once
  const [initialEvents] = React.useState(() => createSampleEvents(new Date()));

  return (
    <CalendarProvider
      defaultEvents={initialEvents}
      // India's hours beside yours, half an hour off any whole-hour zone
      secondaryTimeZone="Asia/Kolkata"
    >
      <WeekView scrollToHour={8} />
    </CalendarProvider>
  );
}
```

`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.

```tsx
<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](/docs/components/calendar) and [Calendar App](/docs/components/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](/docs/components/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](#creating-events) 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`](#time-zone) 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.

```tsx
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](/docs/components/calendar-sidebar)'s "Meet with..." field and the [People Picker](/docs/components/people-picker) (F and P in [Calendar App](/docs/components/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

Live example, interactive at https://calendarcn.xyz/docs/components/calendar-core. Its source:

```tsx title="src/examples/custom-event-content-demo.tsx"
"use client";

import * as React from "react";
import { MapPinIcon, RepeatIcon } from "lucide-react";

import { cn } from "@/lib/utils";
import { CalendarProvider } from "@/components/calendar-provider";
import { WeekView } from "@/components/week-view";
import type {
  DetailedCalendarEvent,
  EventColor,
  EventContentProps,
} from "@/components/calendar-types";
import { createSampleEvents } from "@/lib/sample-events";

/** Text class per event color, from the `--event-*` theme tokens */
const TEXT_CLASS: Record<EventColor, string> = {
  red: "text-event-red",
  orange: "text-event-orange",
  yellow: "text-event-yellow",
  green: "text-event-green",
  blue: "text-event-blue",
  purple: "text-event-purple",
  gray: "text-event-gray",
};

export function CustomEventContentDemo() {
  // The provider reads its initial events once, so create them once
  const [initialEvents] = React.useState(() => createSampleEvents(new Date()));

  return (
    <CalendarProvider
      defaultEvents={initialEvents}
      renderEventContent={renderEventContent}
    >
      <WeekView scrollToHour={8} />
    </CalendarProvider>
  );
}

/**
 * Draws the inside of every event. The calendar still draws the box around
 * it (position, color, selection, drag and resize handles).
 */
function renderEventContent({
  event,
  placement,
  isCompact,
  timeLabel,
}: EventContentProps<DetailedCalendarEvent>) {
  const textClass = cn(
    "text-[0.625rem] leading-tight dark:text-white/85",
    TEXT_CLASS[event.color ?? "blue"],
  );

  // One line: the all-day row, month cells, and short time-grid blocks
  if (isCompact || placement !== "time-grid") {
    return (
      <div className={cn("flex h-full items-center gap-1", textClass)}>
        {event.recurrence && <RepeatIcon className="size-2.5 shrink-0" />}
        <span className="truncate font-semibold">{event.title}</span>
      </div>
    );
  }

  return (
    <div className={cn("flex h-full flex-col gap-0.5 pt-0.5", textClass)}>
      <span className="font-semibold">{event.title}</span>
      <span className="tabular-nums opacity-80">{timeLabel}</span>
      {event.location && (
        <span className="flex items-center gap-0.5 opacity-80">
          <MapPinIcon strokeWidth={1.5} className="size-2.5 shrink-0" />
          <span className="truncate">{event.location}</span>
        </span>
      )}
    </div>
  );
}
```

`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](/docs/components/agenda-view) (`"agenda"`). `isCompact` is true wherever there's room for one line only.

To replace the details popover instead, see [Event Details](/docs/components/event-details#custom-details).

## Typed events

Live example, interactive at https://calendarcn.xyz/docs/components/calendar-core. Its source:

```tsx title="src/examples/typed-events-demo.tsx"
"use client";

import * as React from "react";
import { DoorOpenIcon, UsersIcon } from "lucide-react";

import { CalendarProvider, useCalendar } from "@/components/calendar-provider";
import { WeekView } from "@/components/week-view";
import { Button } from "@/components/ui/button";
import type {
  CalendarEvent,
  EventContentProps,
  EventDetailsRenderProps,
  NewEventRange,
} from "@/components/calendar-types";
import { createSampleEvents } from "@/lib/sample-events";

/** Your own event type: the calendar's fields plus anything your app needs */
interface Meeting extends CalendarEvent {
  room: string;
  attendees: string[];
}

/** Rooms handed out to the sample meetings, in turn */
const ROOMS = ["Atlas", "Borealis", "Cosmos"];

/** Attendees handed out to the sample meetings, in turn */
const PEOPLE = ["Ana", "Sam", "Lee", "Kai", "Noor"];

/** Turns the shared sample events into meetings with a room and attendees */
function createSampleMeetings(): Meeting[] {
  return createSampleEvents(new Date()).map((event, index) => ({
    id: event.id,
    title: event.title,
    start: event.start,
    end: event.end,
    isAllDay: event.isAllDay,
    color: event.color,
    room: ROOMS[index % ROOMS.length],
    attendees: PEOPLE.slice(0, (index % PEOPLE.length) + 1),
  }));
}

/**
 * Builds the meeting a double-click or a drag on empty space starts.
 * Required here: the calendar's default untitled event has no `room` or
 * `attendees`, so TypeScript asks for this factory as soon as `Meeting`
 * adds required fields.
 */
function createMeeting(range: NewEventRange): Meeting {
  return {
    id: crypto.randomUUID(),
    title: "",
    start: range.start,
    end: range.end,
    color: "blue",
    room: ROOMS[0],
    attendees: [],
  };
}

export function TypedEventsDemo() {
  // `Meeting` is inferred from `defaultEvents`, so every callback and
  // renderer below receives a `Meeting`, not a plain `CalendarEvent`
  const [initialEvents] = React.useState(createSampleMeetings);

  return (
    <CalendarProvider
      defaultEvents={initialEvents}
      createEvent={createMeeting}
      renderEventContent={renderMeetingContent}
      renderEventDetails={renderMeetingDetails}
    >
      <WeekView scrollToHour={8} />
    </CalendarProvider>
  );
}

/** Event content with the room under the title */
function renderMeetingContent({
  event,
  isCompact,
}: EventContentProps<Meeting>) {
  return (
    <div className="flex h-full min-w-0 flex-col pt-0.5 text-[0.625rem] leading-tight text-foreground/80">
      <span className="truncate font-semibold">{event.title}</span>
      {!isCompact && (
        <span className="flex items-center gap-0.5 opacity-80">
          <DoorOpenIcon strokeWidth={1.5} className="size-2.5 shrink-0" />
          <span className="truncate">{event.room}</span>
        </span>
      )}
    </div>
  );
}

/** Popover body for a meeting */
function renderMeetingDetails(props: EventDetailsRenderProps<Meeting>) {
  return <MeetingDetails {...props} />;
}

function MeetingDetails({ event, close }: EventDetailsRenderProps<Meeting>) {
  const { updateEvent } = useCalendar<Meeting>();

  return (
    <div className="flex flex-col gap-3 p-3 text-sm">
      <p className="font-semibold">{event.title}</p>
      <div className="flex flex-col gap-1.5 text-xs text-muted-foreground">
        <span className="flex items-center gap-1.5">
          <DoorOpenIcon strokeWidth={1.5} className="size-3.5" />
          {event.room}
        </span>
        <span className="flex items-center gap-1.5">
          <UsersIcon strokeWidth={1.5} className="size-3.5" />
          {event.attendees.length > 0
            ? event.attendees.join(", ")
            : "No attendees yet"}
        </span>
      </div>
      <div className="flex gap-2">
        <Button
          variant="secondary"
          size="sm"
          onClick={() =>
            updateEvent({
              ...event,
              room: ROOMS[(ROOMS.indexOf(event.room) + 1) % ROOMS.length],
            })
          }
        >
          Change room
        </Button>
        <Button variant="ghost" size="sm" onClick={close}>
          Done
        </Button>
      </div>
    </div>
  );
}
```

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](#creating-events), so TypeScript asks you to.

```tsx
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 | Description |
| --- | --- | --- | --- |
| `events` | `TEvent[]` | – | Events to display (controlled). Pair with `onEventsChange`. |
| `defaultEvents` | `TEvent[]` | `[]` | Initial events when `events` is not controlled. |
| `onEventsChange` | `(events: TEvent[]) => void` | – | 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. |
| `view` | `"day" \| "week" \| "month" \| "agenda" \| "year"` | – | Active view (controlled). |
| `defaultView` | `"day" \| "week" \| "month" \| "agenda" \| "year"` | `"week"` | Initial view when `view` is not controlled. |
| `onViewChange` | `(view: ViewType) => void` | – | Called when the view changes. |
| `date` | `Date` | – | First day of the displayed period (controlled). |
| `defaultDate` | `Date` | – | 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. |
| `onDateChange` | `(date: Date) => void` | – | Called when the displayed date changes, by navigation or by scrolling. |
| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | – | Day the week starts on, 0 for Sunday to 6 for Saturday (controlled). Every view and the mini calendar follow it. |
| `defaultWeekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `0` | Initial week start when `weekStartsOn` is not controlled. "Start week on..." in the command menu changes it. |
| `onWeekStartsOnChange` | `(weekStartsOn: WeekStartsOn) => void` | – | Called when the week start changes. |
| `numberOfDays` | `number` | – | 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. |
| `defaultNumberOfDays` | `number` | `7` | Initial number of days when `numberOfDays` is not controlled. |
| `onNumberOfDaysChange` | `(numberOfDays: number) => void` | – | Called when the number of days changes. |
| `hourHeight` | `number \| null` | – | 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). |
| `defaultHourHeight` | `number \| null` | `null` | Initial hour height when `hourHeight` is not controlled. |
| `onHourHeightChange` | `(hourHeight: number \| null) => void` | – | Called when the hour height changes: zooming in or out, or back to the default size. Store it to keep the size across visits. |
| `defaultViewSettings` | `Partial<ViewSettings>` | `{ showWeekends: true, showDeclinedEvents: true, showWeekNumbers: false }` | Initial display preferences. Toggle them later with `toggleWeekends`, `toggleDeclinedEvents` and `toggleWeekNumbers`. |
| `snapMinutes` | `number` | `15` | Minute step that timed-event drag, resize and new events snap to. Also the shortest length a resize or a drawn event allows. |
| `defaultEventDuration` | `number` | `30` | Length in minutes of an event created by double-clicking an empty time slot, as in Notion Calendar. |
| `dayStartHour` | `number` | `0` | 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. |
| `dayEndHour` | `number` | `24` | 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. |
| `hourCycle` | `12 \| 24` | `12` | Clock style for every time label: "3 PM" or "15:00". |
| `locale` | `Locale` | `enUS` | date-fns locale for day names, month names, dates and week numbers. |
| `secondaryTimeZone` | `string` | – | 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). |
| `secondaryTimeZones` | `string[]` | – | 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). |
| `defaultSecondaryTimeZones` | `string[]` | `[]` | Initial additional zones when `secondaryTimeZones` isn't controlled. |
| `onSecondaryTimeZonesChange` | `(timeZones: string[]) => void` | – | Called when the additional zones change from the time axis labels or the command menu. |
| `timeZone` | `string` | – | 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). |
| `defaultTimeZone` | `string` | – | Initial `timeZone` when it isn't controlled. Defaults to the viewer's zone. |
| `onTimeZoneChange` | `(timeZone: string) => void` | – | Called when the primary zone changes from the time axis labels or the command menu ("Make time zone primary", "Add as primary time zone"). |
| `calendars` | `CalendarInfo[]` | `[]` | 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. |
| `contacts` | `EventContact[]` | `[]` | People the details' participants field suggests: the `recent` ones on focus, the matches while typing. A typed email can be invited without one. |
| `rooms` | `EventRoom[]` | `[]` | 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. |
| `conferenceProviders` | `ConferenceProviderOption[]` | `[]` | 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. |
| `locationSuggestions` | `LocationSuggestion[]` | `[]` | Places the details' location field lists under the typed text while typing. |
| `meetWith` | `string[]` | – | 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). |
| `defaultMeetWith` | `string[]` | `[]` | People met with at first when `meetWith` is not controlled. |
| `onMeetWithChange` | `(meetWith: string[]) => void` | – | Called with the new emails when someone is added to or taken out of the meeting. |
| `teammates` | `string[]` | – | Emails of the teammates whose calendars show beside yours (controlled), as "Show teammate calendar..." adds them. |
| `defaultTeammates` | `string[]` | `[]` | Teammates shown at first when `teammates` is not controlled. |
| `onTeammatesChange` | `(teammates: string[]) => void` | – | Called with the new emails when a teammate's calendar is shown or hidden. |
| `contactEvents` | `Record<string, DetailedCalendarEvent[]>` | `{}` | 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. |
| `workingHours` | `WorkingHours` | `9 AM to 5 PM, Monday to Friday` | 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. |
| `createEvent` | `(range: NewEventRange) => TEvent \| null` | – | 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. |
| `onEventCreate` | `(event: TEvent) => void` | – | 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. |
| `onEventUpdate` | `(event: TEvent) => void` | – | 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. |
| `onEventDelete` | `(event: TEvent) => void` | – | Called after an event is removed: deleted, cut, or taken away by `undo` or `redo` (an undone create, duplicate or paste). |
| `onEventSelect` | `(eventId: string) => void` | – | 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). |
| `onVisibleRangeChange` | `(range: VisibleRange) => void` | – | 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). |
| `loading` | `boolean` | `false` | 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. |
| `renderEventContent` | `(props: EventContentProps<TEvent>) => ReactNode` | – | Draws the inside of each event in the hour grid, the all-day row and month view. Defaults to the title and time. |
| `renderEventDetails` | `(props: EventDetailsRenderProps<TEvent>) => ReactNode` | – | Draws the body of the details popover. Defaults to `EventDetailPanel`. |
| `children` | `ReactNode` | – | The views and your own components that read calendar state. |

### 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 | Description |
| --- | --- | --- |
| `events` | `TEvent[]` | 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). |
| `view` | `"day" \| "week" \| "month" \| "agenda" \| "year"` | Active view. |
| `currentDate` | `Date` | First day of the displayed period. |
| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | Day the week starts on. |
| `numberOfDays` | `number` | Days the week view shows. |
| `hourHeight` | `number \| null` | Height of an hour in the day and week views, in pixels, or `null` at the default size, which fills the screen. |
| `viewSettings` | `ViewSettings` | `showWeekends`, `showDeclinedEvents` and `showWeekNumbers`, which every view reads. See [Calendar Header](/docs/components/calendar-header#calendarviewswitcher). |
| `visibleDays` | `Date[]` | 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. |
| `displayMonth` | `Date \| null` | First day of the month the month view shows (it follows its scroll), or `null` before month view has rendered. |
| `visibleRange` | `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. |
| `loading` | `boolean` | Whether the provider's `loading` prop is set. |
| `selectedEventId` | `string \| null` | ID of the selected event. `null` while several are selected: `selectedEventIds` lists them, and none shows its details. |
| `selectedEventIds` | `string[]` | IDs of every selected event, in the order they were picked: the one `selectedEventId` names, or several. Empty when nothing is selected. |
| `selectedEvent` | `TEvent \| null` | The selected event: a stored one, or the generated occurrence its id names. |
| `previousInSeries` | `SeriesOccurrence<TEvent> \| null` | 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. |
| `nextInSeries` | `SeriesOccurrence<TEvent> \| null` | The selected event's next occurrence in its series, or `null` at the series' end. |
| `showSeriesOccurrence` | `(occurrence: SeriesOccurrence<TEvent>) => void` | 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. |
| `timeZones` | `CalendarTimeZones` | The zones beside the time axis: `primary` (`timeZone`, `undefined` for the viewer's) and `secondary`, left to right. |
| `changeTimeZones` | `(change: (zones: CalendarTimeZones) => CalendarTimeZones) => void` | 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`. |
| `travelTimeZone` | `string \| null` | 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). |
| `travelToTimeZone` | `(timeZone: string \| null) => void` | Travels to a zone; `null` travels back home. |
| `highlightedDate` | `Date \| null` | Day briefly highlighted after `showDay`. |
| `monthName` | `string` | 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. |
| `year` | `string` | Four-digit year for a header ("2026"). |
| `weekNumber` | `number` | Week number of the displayed week. |
| `goToToday` | `() => void` | Goes to the period that contains today. |
| `goToPrev` | `() => void` | Goes back one period: a day, a week (or `numberOfDays`), a month, a year or the agenda's 30 days. |
| `goToNext` | `() => void` | Goes forward one period. |
| `goToDate` | `(date: Date) => void` | Sets the first displayed day as given, without snapping to a week start. |
| `switchView` | `(view: ViewType) => void` | Switches the view and snaps the date to the new view's period. |
| `setNumberOfDays` | `(numberOfDays: number) => void` | Sets how many days the week view shows. |
| `setWeekStartsOn` | `(weekStartsOn: WeekStartsOn) => void` | 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. |
| `zoomHoursIn` | `() => void` | Makes the hours one step taller (`HOUR_HEIGHT_STEPS`), up to 160px. |
| `zoomHoursOut` | `() => void` | Makes the hours one step shorter (`HOUR_HEIGHT_STEPS`), down to 24px. |
| `resetHourHeight` | `() => void` | Goes back to the default hour size, which fills the screen. |
| `selectEvent` | `(eventId: string) => void` | Selects an event, which opens its popover. |
| `clearSelection` | `() => void` | Clears the selection and closes the popover. Throws an unsaved `eventDraft` away, or saves it when a title was typed into it. |
| `eventDraft` | `TEvent \| null` | The event being created: drawn and selected, but not in `events` yet. See [Creating events](#creating-events). |
| `startEventDraft` | `(range: NewEventRange) => void` | 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. |
| `updateEventDraft` | `(event: TEvent) => void` | Changes the draft without saving it, to preview what is being typed. Ignored unless the event has the draft's id. |
| `setSelectedEventIds` | `(eventIds: string[]) => void` | Selects these events: none clears the selection, one selects it as `selectEvent` does, several select them together. |
| `toggleEventSelection` | `(eventId: string) => void` | Adds an event to the selection, or takes it out: what Shift- and Cmd-click do. |
| `selectAllVisible` | `() => void` | Selects every event on the dates on screen, scrolled-out hours too (Notion Calendar's Select all visible, ⌘A). Does nothing in year view. |
| `addEventFromRange` | `(range: NewEventRange) => void` | Adds an event for a range through `createEvent` at once, selects it and focuses its title. `startEventDraft` waits for a first edit instead. |
| `updateEvent` | `(event: TEvent, scope?: SeriesEditScope) => void` | 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). |
| `editEvent` | `(event: TEvent) => void` | 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. |
| `deleteEvent` | `(eventId: string, scope?: SeriesEditScope) => void` | 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. |
| `duplicateEvent` | `(eventId: string) => void` | 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. |
| `copyEvent` | `(eventId: string) => void` | Keeps a copy of the event for `pasteEvent`. Changes no event. |
| `cutEvent` | `(eventId: string) => void` | Keeps a copy of the event for `pasteEvent`, then deletes it. Undoable. |
| `pasteEvent` | `() => void` | 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. |
| `undo` | `() => void` | 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. |
| `redo` | `() => void` | Does again the latest step `undo` took back. |
| `canUndo` | `boolean` | 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). |
| `canRedo` | `boolean` | Whether `redo` has a step to do again. Any new change clears them. |
| `toggleWeekends` | `() => void` | 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. |
| `toggleDeclinedEvents` | `() => void` | Shows or hides the events you declined (see `isDeclinedByViewer`). Hiding them clears the selection when the selected event is one. |
| `toggleWeekNumbers` | `() => void` | Shows or hides week numbers. |
| `showDay` | `(date: Date) => void` | Opens the week containing `date` and briefly highlights that day. |
| `navigateToDate` | `(date: Date) => void` | 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. |
| `addEventAtNextSlot` | `() => void` | 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. |

### 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 | Description |
| --- | --- | --- |
| `snapMinutes` | `number` | Snap step in minutes. |
| `defaultEventDuration` | `number` | Length in minutes of a double-clicked event. |
| `dayStartHour` | `number` | First visible hour, normalized to 0–23. |
| `dayEndHour` | `number` | Last visible hour, normalized to after `dayStartHour` and at most 24. |
| `hourCycle` | `12 \| 24` | Clock style. |
| `locale` | `Locale` | date-fns locale. |
| `secondaryTimeZone` | `string \| undefined` | IANA id of the first additional time zone column, or `undefined` when there is none. |
| `secondaryTimeZones` | `string[]` | IANA ids of the additional time zone columns, left to right, without zones the runtime doesn't know. |
| `timeZone` | `string \| undefined` | 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. |
| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | First day of the week, for date pickers. Unset outside a provider, where the locale's applies. |
| `calendars` | `CalendarInfo[]` | 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. |
| `contacts` | `EventContact[]` | People the participants field suggests. |
| `rooms` | `EventRoom[]` | Meeting rooms the participants field offers. |
| `conferenceProviders` | `ConferenceProviderOption[]` | Video call services the details offer. |
| `locationSuggestions` | `LocationSuggestion[]` | Places the location field suggests. |

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

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

### CalendarNotice

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

### CalendarEvent

The fields the calendar needs to place and draw an event. [`DetailedCalendarEvent`](/docs/components/event-details#detailedcalendarevent) adds the fields the default details panel reads and edits.

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` | Unique identifier. |
| `title` (required) | `string` | Event title. |
| `start` (required) | `Date` | Start date and time. |
| `end` (required) | `Date` | 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`. |
| `isAllDay` | `boolean` | Draws the event in the all-day row. Timed events that cross midnight go there too. |
| `color` | `"red" \| "orange" \| "yellow" \| "green" \| "blue" \| "purple" \| "gray"` | 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. |

### EventContentProps

Passed to `renderEventContent`.

| Field | Type | Description |
| --- | --- | --- |
| `event` | `TEvent` | The event, with its in-progress start and end while it's dragged or resized. |
| `view` | `"day" \| "week" \| "month" \| "agenda" \| "year"` | View the event is drawn in. |
| `placement` | `"time-grid" \| "all-day" \| "month-item" \| "month-bar" \| "agenda"` | Where the event is drawn, which sets how much room it has. |
| `isSelected` | `boolean` | Whether the event is selected. |
| `isPast` | `boolean` | Whether the event has already ended. |
| `isDragging` | `boolean` | Whether this is the copy that follows the pointer while dragging. |
| `isResizing` | `boolean` | Whether the event is being resized. |
| `isCompact` | `boolean` | Whether there's room for one line only: hour-grid blocks under 40px tall, and always in the all-day row and month view. |
| `timeLabel` | `string` | 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. |

### 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 | Description |
| --- | --- | --- |
| `start` | `Date` | Start, snapped to `snapMinutes`. For whole days, midnight that starts the first day. |
| `end` | `Date` | 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. |
| `isAllDay` | `boolean` | 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. |

### VisibleRange

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

| Field | Type | Description |
| --- | --- | --- |
| `start` | `Date` | Midnight that starts the first visible day. |
| `end` | `Date` | Midnight after the last visible day (exclusive). |

### CalendarInfo

An entry of the `calendars` prop.

| Field | Type | Description |
| --- | --- | --- |
| `id` (required) | `string` | Stored in the event's `calendarId` when picked. |
| `name` (required) | `string` | Display name. |
| `color` (required) | `EventColor` | 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. |
| `email` | `string` | Account the calendar belongs to. The picker and the menu group calendars by it, and a moved event's `calendarEmail` becomes it. |
| `defaultReminders` | `EventReminder[]` | 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`. |

### 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 | Description |
| --- | --- | --- |
| `resolveEventColor` | `(event, calendars) => EventColor` | The color an event is drawn in: its own `color`, else its calendar's, else `DEFAULT_EVENT_COLOR`. |
| `DEFAULT_EVENT_COLOR` | `EventColor` | `"blue"`, for an event without a color whose calendar isn't listed. |
| `moveEventToCalendar` | `(event, to, calendars) => TEvent` | 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`. |
| `groupCalendarsByEmail` | `(calendars) => CalendarGroup[]` | Calendars grouped by account `email` (`{ email?, calendars }`), in the order given. |
| `addReminder` | `(reminders, reminder) => EventReminder[]` | The reminders with one added, sorted by when each fires. Returns `reminders` itself when one firing at the same moment is already set. |
| `getReminderMinutes` | `(reminder) => number` | 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. |
| `isSameReminder` | `(a, b) => boolean` | Whether two reminders fire at the same moment, as 60 min and 1 hour do. |

### 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 | Description |
| --- | --- | --- |
| `expandRecurringEvents` | `(events, range: VisibleRange, timeZone?: string) => TEvent[]` | 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. |
| `findEventOrOccurrence` | `(events, id, timeZone?: string) => TEvent \| null` | 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. |
| `applyRecurringEdit` | `(events, previous, edited) => TEvent` | 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. |
| `findEventSeries` | `(events, event) => TEvent \| null` | 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. |
| `getSeriesEditScopes` | `(events, before, after) => SeriesEditScope[]` | 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. |
| `getSeriesDeleteScopes` | `(events, event) => SeriesEditScope[]` | The options for deleting a date: `["this", "all"]` on the first date, else all three. |
| `getSeriesEditChanges` | `(options: SeriesEditOptions) => SeriesEditResult` | 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. |
| `getSeriesDeleteChanges` | `(options: SeriesDeleteOptions) => EventHistoryChange[]` | What deleting a date with an option changes, in the same order. |

### EventContact

An entry of the `contacts` prop.

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

### 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 | Description |
| --- | --- | --- |
| `days` (required) | `(0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6)[]` | Days of the week they apply to, 0 (Sunday) to 6 (Saturday). |
| `startHour` (required) | `number` | Hour (0-23) they start at. |
| `endHour` (required) | `number` | Hour (1-24) they end at, after `startHour`. |

### 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`](/docs/components/event-details#conference-providers) has placeholder Google Meet, Zoom and Microsoft Teams options to start from.

| Field | Type | Description |
| --- | --- | --- |
| `provider` (required) | `"google-meet" \| "zoom" \| "microsoft-teams" \| "other"` | Service the call is hosted on, stored in the call. |
| `label` (required) | `string` | 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`. |
| `icon` | `React.ReactNode` | 16px icon in the menu and on the event. Defaults to a camera. |
| `hint` | `string` | Muted text at the end of the menu item, e.g. "Connect". |
| `createConference` (required) | `(event: DetailedCalendarEvent) => EventConference \| Promise<EventConference>` | 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. |

```tsx
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 | Description |
| --- | --- | --- |
| `name` (required) | `string` | Name of the place, e.g. "Central Park". |
| `address` | `string` | Shown under the name, and saved after it: "Central Park, New York, NY, USA". |
