Calendar

Preview

A product team reviews onboarding, synthesizes research, protects focus time, and plans a release across the next three days. Open an event for its organizer, attendees, location, notes, and meeting link. Accept or dismiss the suggested focus block to see caller-owned AI scheduling state change.

Design guidance

Use Calendar for dated events that need more than date selection. Choose a view that matches the task: agenda for a short list, day or three-day for scheduling, week for planning, month for date context, or schedule to compare resources. Keep time zones explicit. Timed values need an ISO offset; all-day end dates are exclusive. Give events stable IDs and keep persistence, invitation policy, and AI decisions in the caller.

The React view is still React. Its date, interval, validation, and lane helpers are plain TypeScript and can be consumed from the calendar-core entry without mounting the UI.

Installation

npx shadcn@latest add https://ghost-ui.com/r/calendar.json

Calendar composes Dialog, Avatar, Button, ScrollArea, EmptyState, Link, and Separator. The registry item includes those dependencies.

Load the shared foundation and Button styles once in your application entry. Calendar imports its own stylesheet.

12import "@/components/ui/foundation.css";
import "@/components/ui/button.css";

Install Field and Input when you use the caller-owned creation dialog shown in the Preview.

Basic usage

123456789101112import { Calendar } from "@/components/ui/calendar";
import type { CalendarEvent } from "@/components/ui/calendar.types";

const events: CalendarEvent[] = [{
  id: "research-review",
  title: "Research review",
  start: "2026-10-07T10:00+07:00",
  end: "2026-10-07T10:45+07:00",
  location: "Studio 2",
}];

<Calendar events={events} date="2026-10-07" timeZone="Asia/Jakarta" view="day" />

Structures

The component renders its navigation, date grid, event cards, and detail or overflow dialog. Pass resources and event data from the caller. Use renderEvent when the card content needs product-specific treatment; the calendar still owns its event wrapper and interactions.

Examples

Agenda list

Use agenda to scan the day's events in chronological order and open details without a time grid.

<Calendar events={events} date="2026-10-07" timeZone="Asia/Jakarta" view="agenda" />

Daily schedule

Use a day view when the team needs one detailed timeline. Empty timed slots can open a caller-owned creation flow.

<Calendar events={events} date="2026-10-07" timeZone="Asia/Jakarta" view="day" onSlotSelect={openCreateDialog} />

Three-day planning

Compare adjacent days on one time axis. The Preview uses this view for the team's immediate plan.

<Calendar events={events} date="2026-10-07" timeZone="Asia/Jakarta" view="three-day" />

Week planning

Use the Monday-first week for broader planning. The caller owns the selected date and view when they need to control navigation.

123const [date, setDate] = React.useState("2026-10-07");
const [view, setView] = React.useState<CalendarView>("week");
<Calendar events={events} date={date} timeZone="Asia/Jakarta" view={view} onDateChange={setDate} onViewChange={setView} />

Month context

Use the month grid for date context. Crowded dates reveal the remaining events in a dialog.

<Calendar events={events} date="2026-10-07" timeZone="Asia/Jakarta" view="month" />

Resource schedule

Pass resources and matching resourceId values to compare team calendars. Unassigned events remain visible in the unassigned column.

<Calendar events={events} resources={[{ id: "mina", label: "Mina Patel" }]} date="2026-10-07" timeZone="Asia/Jakarta" view="schedule" />

Controlled edits and creation

Set editable and provide onEventChange to enable move and resize gestures in a time or date grid. Agenda remains a read-only chronological list. The callback returns a new event with its original metadata; update your controlled events value to commit it. Escape, cancellation, and invalid drops do not commit. onSlotSelect receives a draft range; create the event in your own dialog and add it only after the user submits.

123<Calendar events={events} date={date} timeZone={timeZone} view="three-day" editable
  onEventChange={(next) => setEvents(current => current.map(event => event.id === next.id ? next : event))}
  onSlotSelect={(slot) => setDraft(slot)} />

slotDuration defaults to 30 minutes and snapDuration to 15 minutes. Click or keyboard selection uses the same snapped slot. Move with Alt+Arrow keys; resize handles use Arrow keys. Timed events resize vertically; all-day and month events resize by date.

Overlap and overflow

Overlapping timed events use up to three visible lanes. Open +N to reach every hidden event. Adjacent events can reuse a lane.

<Calendar events={events} date="2026-10-07" timeZone="Asia/Jakarta" view="day" />

Event details and responses

Organizer, participants, location, notes, link, status, and conflict are event data. Pending response actions appear only when onEventResponse is supplied; update the controlled event after the caller accepts or declines.

12<Calendar events={events} date={date} timeZone={timeZone}
  onEventResponse={(event, status) => updateEvent(event.id, { status })} />

AI suggestion and scheduled provenance

Scheduling provenance is independent from invitation status. The callback requests an action; the caller decides what it means and updates the event. Accepting a suggestion changes its state to scheduled while retaining its AI source and reason.

12<Calendar events={events} date={date} timeZone={timeZone}
  onSchedulingResponse={(event, response) => applySchedulingPolicy(event, response)} />

Read-only data states

Without editable, event changes are disabled. Invalid data produces a visible alert. Empty data, very short events, midnight continuation, daylight-saving transitions, and event kinds are also represented in these examples.

Career history remains owned by Timeline. Date Picker owns date selection; Booking keeps its private date/time strip.

API reference

Source utilities

Import the framework-free date and layout helpers from the installed calendar.utils source (or the import package’s calendar-core entry) when a caller needs the same date validation, zone conversion, interval splitting, or lane layout without rendering the React view.

12345import { addCalendarDays, getCalendarDay } from "@/components/ui/calendar.utils";

const tomorrow = addCalendarDays("2026-10-07", 1);
const day = getCalendarDay(tomorrow, "Asia/Jakarta");
// day.startMs and day.endMs are the actual instants for this local date.

Keyboard and accessibility

Tab reaches calendar controls, events, and the slot grid when creation is enabled. Enter or Space opens event details. Escape closes dialogs and cancels an unfinished gesture. Alt+Arrow keys move a focused editable event; resize handles use Arrow keys. Empty timed cells support arrow-key slot selection and Enter. Event and slot controls expose accessible names and status feedback.