Calendar and scheduling

Choose a layer

Use the core when your task needs validated date math, interval splitting, lanes, or edit proposals without a view. Add Calendar to browse and interact with events; use Booking when a person chooses availability and confirms an appointment. For date or time entry, use Date input, Date picker, Time input, or Time picker.

Install and try the core

The package exposes @ghost-ui/core/calendar-core. Follow the installation guide for the source registry or local package artifact; the repository's package export does not establish a published release. This entry has no React or stylesheet dependency.

12345import { getCalendarDay, parseCalendarDate } from "@ghost-ui/core/calendar-core";

const date = "2026-10-26";
const day = getCalendarDay(date, "America/Los_Angeles");
console.log(parseCalendarDate(date), day.minutes);

YYYY-MM-DD is a calendar date, not an instant. The day calculation uses the supplied IANA timezone and can return 1,380 or 1,500 minutes across daylight-saving transitions.

First React integration

The package view is React UI built on the same core contracts. Follow package installation for shared styles, then supply the current event collection and navigation date. This example applies edit proposals locally; it does not save them to a server.

12345678910111213import { useState } from "react";
import { Calendar } from "@ghost-ui/core/components/calendar";
import type { CalendarEvent } from "@ghost-ui/core/calendar-core";
export function TeamCalendar() {
  const [date, setDate] = useState("2026-10-30");
  const [events, setEvents] = useState<CalendarEvent[]>([{
    id: "review", title: "Design review",
    start: "2026-10-30T09:00:00+07:00", end: "2026-10-30T09:30:00+07:00",
  }]);
  return <Calendar date={date} onDateChange={setDate} timeZone="Asia/Jakarta"
    events={events} editable onEventChange={next => setEvents(current =>
      current.map(event => event.id === next.id ? next : event))} />;
}

To extend event content, use the view's renderEvent callback; keep event identity and interaction with Calendar. Use core interval/layout operations for another presentation, and keep application-only fields in your domain records keyed by event ID. State and operations covers persistence, conflicts and editing. See Calendar API for calculations and component API for rendering options.

Follow the data contract

The caller supplies events, resources, the visible date, and timezone. Timed event timestamps must include Z or an explicit numeric offset. All-day end is exclusive. Read Calendar data for identity, event shape, validation, interval boundaries, and resource lanes.

Apply state changes

Core functions return calculations or a new event proposal; they do not save data. A React Calendar reports requested selection, slot, view, date, response, or edit changes through callbacks. The caller applies accepted event changes to its controlled events and handles persistence, conflicts, and failure feedback. Read Calendar state for edit and timezone behavior.

API reference

See Calendar API for the current core exports, signatures, defaults, and validation failures. Use the Calendar component page for view anatomy, styling, and interaction examples. These contracts do not provide recurrence or server-side scheduling.

Troubleshooting

If navigation does not change the view, update the controlled date/view after its callback. If an event lands on another day, compare its instant with the selected timezone before changing the stored value. If an edit is ignored, check editable, the event's edit permission, point/duration restrictions and snapping. Validate incoming records before debugging their rendering.