Calendar and views

This reference covers the root calendar, shared behavior, built-in views, and custom view registration. Start with the API overview to find another contract area.

Calendar

Calendar owns shared behavior and forwards view-specific configuration under viewProps. Its generic parameters are Event, Resource, and Views.

<Calendar<Meeting, Room>
    view="week"
    events={meetings}
    timeZone="UTC"
    viewProps={{ resources: roomConfig, minTime: "08:00" }}
/>

Root props

All shared view props are also accepted at the root. Unknown view names throw Error: Calendar view "<name>" is not registered.

View registry types

CalendarBuiltInView is "agenda" | "day" | "month" | "time-grid" | "week". CalendarViewProps<View> extracts only the configuration owned by one built-in view. CalendarViewRegistration is a React component or a CalendarViewDefinition. CalendarViewRegistry maps names to registrations.

import type { SharedViewProps } from "@chronolanejs/react";

interface QuarterProps extends SharedViewProps<Meeting> {
    heading?: string;
}

function QuarterView({ events = [], heading = "Quarter" }: QuarterProps) {
    return <section><h2>{heading}</h2><p>{events.length} events</p></section>;
}

const views = {
    quarter: {
        component: QuarterView,
        defaultProps: { heading: "Launch quarter" }
    }
};

<Calendar<Meeting, unknown, typeof views>
    view="quarter"
    views={views}
    viewProps={{ heading: "Q3" }}
/>

Explicit viewProps override registered defaultProps. The root then owns and overrides forwarded events, backgroundEvents, locale, formatters, messages, and viewName so a custom view receives the same shared contract.

Shared view props

SharedViewProps<Event, Resource> is accepted by every direct view. Calendar accepts the same props except viewName, className, and style, which it owns at the root.

Selection and opening gestures are invariant: an absent callback disables only that semantic and never remaps its gesture. Event roots are focusable when a semantic keyboard action or raw onKeyDown exists, but are not represented as buttons. See Interactions and callbacks for the occurrence context and raw interaction contract.

Navigation boundaries

minDate and maxDate constrain navigation anchors, not rendered data. Each value is normalized to the start of its calendar day in timeZone; the interval is inclusive and minDate must not be after maxDate.

<Calendar
    view="week"
    defaultDate="2026-09-17"
    minDate="2026-09-16"
    maxDate="2026-09-18"
    events={meetings}
/>

The week from September 14 through September 20 still renders in full. Because it partially overlaps both boundaries, both outward navigation directions are disabled. Boundaries never remove outside days or filter overlapping events.

A controlled date outside the interval is rendered unchanged. The direction farther outside is disabled; the direction back toward the interval remains available and its first navigation request is clamped directly to the nearest boundary. The clamped Date is passed to onDateChange, so the application must still update controlled state. Anchors produced by a range's custom navigation.resolveAnchor strategy are validated and clamped by the same rule.

An invalid boundary throws a contextual TypeError. Supplying minDate after maxDate throws RangeError during render.

AgendaView

AgendaView groups each event under the first visible day it overlaps. Multi-day events appear once. It accepts all shared props plus:

MonthView

MonthView renders a complete week-aligned month grid. Each event appears on every day it overlaps.

maxEventsPerDay must be a non-negative integer. It limits visible rows only when onShowMore is provided; otherwise every event remains visible. Month navigation always resolves the previous or next displayed month; custom range navigation belongs only to configurable agenda and time-grid ranges.

DayView, WeekView, and TimeGridView

All three accept TimeGridViewProps<Event, Resource>. DayView defaults to range="day" and viewName="day"; the day preset moves one day. WeekView defaults to range="week" and viewName="week"; the week preset moves seven days. It also keeps day columns fluid down to 96px, then scrolls horizontally. An explicit slotSizing.width or slotSizing.minWidth overrides that minimum. Explicit range values carry their own navigation. TimeGridView defaults to the week preset and viewName="time-grid" without applying a column minimum.

TimeOfDay is strict zero-padded HH:mm. minTime="24:00" is invalid. TimeGridSlotSizing supports { width } or { minWidth }, independently with { height } or { minHeight }. Fixed values must be positive finite numbers; minimum values may be zero.

Resizing changes one source boundary, retains the occurrence resource, and may cross visible days on that resource. Targets follow the resizeStep scale anchored to minTime; a shorter final interval ends exactly at maxTime. The complete proposed event interval is previewed during movement. Pointer release, Enter, or blur commits once after movement. Escape, pointer cancel, and no movement produce no callback.

multiDayEventLayout="dedicated" derives placement exclusively from each half-open start/end interval; it does not add event metadata. An event is multi-day when it crosses a local calendar-day boundary, including overnight events. Dedicated bars span contiguous visible day/resource columns and split around unrelated resource columns. They retain selection/opening behavior, move by visible day/resource columns, and resize in whole calendar-day steps. Background events always remain in the hourly grid. The dedicated region is omitted when no qualifying foreground event is visible.

View definitions

defaultCalendarViews is the immutable built-in registry. A caller entry with the same name overrides a built-in for that Calendar. The registry accepts dynamic string lookup and returns a React element type when the name exists:

const viewName: string = getSavedViewName();
const BuiltInView = defaultCalendarViews[viewName];