Calendar

"use client";import { useState } from "react";import {  CalendarContent,  CalendarHeaderToolbar,  CalendarProvider,  type CalendarEventData,  type CalendarRange,} from "@notion-kit/ui/calendar";export interface CalendarDemoProps {  defaultRange?: CalendarRange;  readOnly?: boolean;}export default function CalendarDemo({  defaultRange = "monthly",  readOnly = false,}: CalendarDemoProps) {  const [events, setEvents] = useState<CalendarEventData[]>(() => {    const now = new Date();    const day = Date.UTC(      now.getUTCFullYear(),      now.getUTCMonth(),      now.getUTCDate(),    );    return [      {        id: "launch",        name: "Launch week",        startAt: day - 2 * 86400000,        endAt: day + 2 * 86400000,        allDay: true,      },      {        id: "review",        name: "Design review",        startAt: day + 10 * 3600000,        endAt: day + 11 * 3600000,        allDay: false,      },      {        id: "planning",        name: "Sprint planning",        startAt: day + 10.5 * 3600000,        endAt: day + 12 * 3600000,        allDay: false,      },      {        id: "overnight",        name: "Overnight release",        startAt: day + 23 * 3600000,        endAt: day + 25 * 3600000,        allDay: false,      },      {        id: "note",        name: "Write release notes",        startAt: day,        endAt: null,        allDay: true,      },    ];  });  const [opened, setOpened] = useState<string | null>(null);  return (    <div className="w-full min-w-0">      <CalendarProvider        events={events}        defaultRange={defaultRange}        timeZone="UTC"        readOnly={readOnly}        className="h-[560px]"        onCreate={(value) =>          setEvents((current) => [            ...current,            { ...value, id: crypto.randomUUID(), name: "New event" },          ])        }        onEventClick={(event) => setOpened(event.name)}        onEventChange={({ id, reason: _reason, ...value }) =>          setEvents((current) =>            current.map((event) =>              event.id === id ? { ...event, ...value } : event,            ),          )        }      >        <CalendarHeaderToolbar />        <CalendarContent />      </CalendarProvider>      <p className="mt-2 text-sm text-secondary" aria-live="polite">        {opened          ? `Opened: ${opened}`          : readOnly            ? "Select an event to open it."            : "Select an event to open it. Select an empty date or time to create one."}      </p>    </div>  );}

Installation

pnpm add @notion-kit/ui

Import these components from @notion-kit/ui/calendar. For a date picker, use Calendar from @notion-kit/ui/primitives.

Anatomy

import {
  CalendarContent,
  CalendarHeaderToolbar,
  CalendarProvider,
} from "@notion-kit/ui/calendar";

<CalendarProvider
  events={events}
  defaultRange="monthly"
  timeZone="America/New_York"
  onCreate={createEvent}
  onEventClick={openEvent}
  onEventChange={changeEvent}
  className="h-[600px]"
>
  <CalendarHeaderToolbar />
  <CalendarContent />
</CalendarProvider>;

The provider owns navigation and temporary gesture state. You own events: apply changes from onCreate and onEventChange to save them. Ignoring a change leaves the original event in place. Omitting a write callback disables its operation. readOnly disables creation, moving, resizing, and conversion; navigation and event opening remain available.

Examples

Week

The week view separates all-day events from timed events. Overlapping events appear in adjacent columns, and events that cross midnight occupy each day they cover. This example uses UTC and saves creation, movement, resizing, and conversion in local React state.

<CalendarProviderevents={events}defaultRange="weekly"timeZone="UTC"onCreate={createEvent}onEventChange={changeEvent}className="h-[560px]"><CalendarHeaderToolbar /><CalendarContent /></CalendarProvider>

Day with controlled navigation

Control range and anchorDate to keep the selected period and viewed date in your application. Apply each navigation callback to update the calendar.

const [range, setRange] = useState<CalendarRange>("daily");const [anchorDate, setAnchorDate] = useState(() => Date.now());<CalendarProviderevents={events}range={range}onRangeChange={setRange}anchorDate={anchorDate}onAnchorDateChange={setAnchorDate}timeZone="UTC"className="h-[560px]"><CalendarHeaderToolbar /><CalendarContent /></CalendarProvider>

Read-only events

Set readOnly to disable event mutations. Users can still change the range, navigate dates, and open events through onEventClick.

<CalendarProviderevents={events}defaultRange="weekly"readOnlyonEventClick={openEvent}className="h-[560px]"><CalendarHeaderToolbar /><CalendarContent /></CalendarProvider>

Custom event cards

Pass renderEvent to replace the default card. Compose CalendarEvent.Root, CalendarEvent.Item, and CalendarEvent.Resize to retain event opening, dragging, and resizing. The layout positions each segment and shows resize handles only at the event's actual boundaries.

<CalendarContentrenderEvent={({ event, segment }) => (  <CalendarEvent.Root event={event} segment={segment}>    <CalendarEvent.Item>{event.name}</CalendarEvent.Item>    <CalendarEvent.Resize edge="start" />    <CalendarEvent.Resize edge="end" />  </CalendarEvent.Root>)}/>

Event dates

interface CalendarEventData {
  id: string;
  name: string;
  startAt: number;
  endAt: number | null;
  allDay: boolean;
}

Timestamps are milliseconds. endAt is exclusive: an all-day event from September 16 through September 18 ends at local midnight on September 19. Use calendar-day arithmetic in the display timezone; a DST day can have 23 or 25 hours. Invalid events are omitted individually. Invalid timezone names fall back to UTC.

A null end displays one local day for all-day events or one hour for timed events. Moving preserves null; resizing creates a real end. Timed events ending exactly at midnight do not occupy the next day. Existing zero-length or short events keep their values and receive a readable minimum height.

The grid shows local 00:00–24:00. New time slots snap to 15 minutes. A missing DST wall time moves forward to a valid time; a repeated wall time selects the earlier offset. Existing timestamps retain their original offset.

Navigation and editing

range supports monthly, weekly, and daily. Use range with onRangeChange, or set defaultRange. The same pattern applies to anchorDate, onAnchorDateChange, and defaultAnchorDate.

Changing range retains the viewed date. Previous and Next move one period; month navigation clamps dates to the last day when needed. Today uses the display timezone. Week and Day initially scroll to 08:00.

Click an empty date or all-day slot to request a one-day event. Click a time slot to request a one-hour event. Enter and Space also activate focused slots and events. Drag any visible event segment to move the whole event; only real start and end boundaries show resize handles. Escape cancels a gesture. Changing period or external event values also cancels it.

Drag between the all-day area and the time grid to convert an event. A three-day all-day event dropped at 10:00 ends at 11:00 on its third day. Timed events converted to all-day retain the dates they cover and discard the hidden time portion. A completed gesture sends one callback.

API reference

CalendarProvider

CalendarEventValue contains startAt, endAt, and allDay. CalendarEventChange adds id and reason, where reason is move, resize-start, resize-end, or convert.

Content and controls

CalendarHeaderToolbar

Combines the period title, range select, and navigation. Also accepts div props; children appear before the range select.

CalendarRangeSelect

CalendarEvent

renderEvent receives CalendarEventRenderProps: the source event and its visible segment. Pass both to Root; keep Item and Resize inside it.

For events backed by table rows and Date properties, see the Table View calendar layout.