Guides
Components
The six rules that cover the whole compound component: plural names, scopes, as, labels and data attributes.
The tree
Calendar is a compound component built on the two hooks. The tedious half comes already wired — geometry, scoping, keys — and everything you see is yours to write. Nothing here is closed off; the pieces arrive pre-wired, not locked down.
import { createCalendarComponents } from '@midstem/chronous-react' import type { CalendarRange, EventInput } from '@midstem/chronous-react' type EventData = { title: string } // Binds your event data to every render prop — see Typed event data below. const Calendar = createCalendarComponents<EventData>() const range: CalendarRange = { view: 'week', currentDate: '2026-03-18', timeZone: 'Europe/Kyiv', } const events: EventInput<EventData>[] = [ { id: 'offsite', start: '2026-03-18', end: '2026-03-20', data: { title: 'Offsite' }, }, { id: 'standup', start: '2026-03-18T09:00', duration: 'PT30M', data: { title: 'Standup' }, }, ] export const Board = () => ( <Calendar.Root className="calendar" range={range} events={events} locale="en-GB" > <Calendar.Header className="grid-header"> <Calendar.DayHeadings className="heading"> {({ weekdayLabel, dayLabel }) => ( <> <span>{weekdayLabel}</span> <strong>{dayLabel}</strong> </> )} </Calendar.DayHeadings> </Calendar.Header> <Calendar.AllDayRow gutterCell="all-day"> <Calendar.AllDayEvents className="bar"> {({ event }) => event.data?.title} </Calendar.AllDayEvents> </Calendar.AllDayRow> <Calendar.TimeGrid hourHeight={60}> <Calendar.TimeAxis className="gutter"> <Calendar.TimeLabels className="tick" /> </Calendar.TimeAxis> <Calendar.DayColumns className="column"> <Calendar.TimeSlots className="line" /> <Calendar.NowMarker className="now" /> <Calendar.TimedEvents as="button" className="event"> {({ event }) => event.data?.title} </Calendar.TimedEvents> </Calendar.DayColumns> </Calendar.TimeGrid> </Calendar.Root> )
MonthGrid / MonthRows / MonthDays cover the month view and AgendaList / AgendaDays the agenda — the full list is in the API reference.
How the pieces fit together
1. A plural name iterates
DayColumns renders one element per day, TimedEvents one per box, TimeSlots one per slot. The repetition is the engine’s, so the component owns the loop and the keys. Singular names — Root, Header, TimeGrid, NowMarker — render once.
2. Scopes and nested elements
Children are a node or a function of the scope. Either way they render inside that scope, so nested components resolve cleanly:
import { Calendar } from '@midstem/chronous-react' import type { CalendarRange, EventInput } from '@midstem/chronous-react' const range: CalendarRange = { view: 'month', currentDate: '2026-03-18', timeZone: 'Europe/Kyiv', } const events: EventInput[] = [ { id: 'review', start: '2026-03-18T14:00', duration: 'PT1H' }, ] export const Month = () => ( <Calendar.Root range={range} events={events} locale="en-GB"> <Calendar.MonthGrid className="month"> <Calendar.MonthRows className="row"> {/* MonthTimedEvents resolves because it renders inside the cell */} <Calendar.MonthDays className="day"> {({ dayLabel, inCurrentPeriod }) => ( <div data-outside={!inCurrentPeriod}> {dayLabel} <Calendar.MonthTimedEvents className="dot" /> </div> )} </Calendar.MonthDays> </Calendar.MonthRows> </Calendar.MonthGrid> </Calendar.Root> )
Every scope is also a hook — useDayColumnContext, useMonthRowContext, useAgendaDayContext and the rest — so a custom component can sit inside a part and read it without a render prop:
import { Calendar, useDayColumnContext } from '@midstem/chronous-react' import type { CalendarRange, EventInput } from '@midstem/chronous-react' // A component of your own: no render prop, no props threaded down. const DayTotal = () => { const { day } = useDayColumnContext() return <span className="total">{day.boxes.length}</span> } export const Board = () => ( <Calendar.Root range={range} events={events}> <Calendar.TimeGrid hourHeight={48}> <Calendar.DayColumns className="column"> <DayTotal /> <Calendar.TimedEvents className="event" /> </Calendar.DayColumns> </Calendar.TimeGrid> </Calendar.Root> )
3. Element markup and style merging
as picks the tag, and your style wins. Every component forwards className, ref, handlers and aria-*, merging computed geometry underneath any style you pass.
<Calendar.TimedEvents as="button" className="event-card" aria-label="Calendar event" onClick={() => openDetails(event.id)} style={{ borderLeft: '4px solid #7c3aed', cursor: 'pointer', }} > {({ event }) => ( <div> <strong>{event.data?.title}</strong> </div> )} </Calendar.TimedEvents>
4. A formatted string ends in Label
weekdayLabel, dayLabel, monthLabel, timeLabel and timeRangeLabel have already been through formatIso in the calendar locale. Everything without the suffix is data: day is a CalendarDay, box a CalendarBox, and bar a CalendarBar.
// Header: weekday and day number strings <Calendar.DayHeadings className="heading"> {({ weekdayLabel, dayLabel, day }) => ( <> <span>{weekdayLabel}</span> <strong>{dayLabel}</strong> </> )} </Calendar.DayHeadings> // Time labels: formatted hours (e.g. '09:00') <Calendar.TimeLabels className="tick"> {({ timeLabel, slot }) => <span>{timeLabel}</span>} </Calendar.TimeLabels> // Events: event data alongside layout box coordinates <Calendar.TimedEvents as="button" className="event"> {({ event, box }) => ( <> <strong>{event.data?.title}</strong> </> )} </Calendar.TimedEvents>
5. Per-item state arrives as data attributes
Because classes are shared by every element a part renders, per-item state arrives as data attributes instead: data-date and data-in-current-period land on day containers, while data-event-id and data-continues-before / data-continues-after land on event elements.
// Per-day state arrives as data attributes: // data-date, data-in-current-period, data-event-id export const Month = () => ( <Calendar.Root range={range} events={[]} locale="en-GB"> <Calendar.MonthGrid className="flex flex-col"> <Calendar.MonthRows className="grid grid-cols-7"> <Calendar.MonthDays className="data-[in-current-period=false]:opacity-40" /> </Calendar.MonthRows> </Calendar.MonthGrid> </Calendar.Root> )
6. The gutter lives on the root
The header, all-day row and time grid lay out the same CSS grid, so gutterWidth is one prop on the root rather than three that can drift apart. Month and agenda ignore it.
Typed event data
Context cannot infer a type argument, so Calendar on its own hands render props data?: unknown. createCalendarComponents binds the namespace once and the type flows to every render prop.
import { createCalendarComponents } from '@midstem/chronous-react' import type { CalendarRange, EventInput } from '@midstem/chronous-react' type EventData = { title: string; owner: string } // A cast, not a factory — it costs nothing and lives at module scope. const Calendar = createCalendarComponents<EventData>() export const Board = () => ( <Calendar.Root range={range} events={events}> <Calendar.TimeGrid hourHeight={48}> <Calendar.DayColumns className="column"> <Calendar.TimedEvents className="event"> {/* event.data is EventData here, not unknown */} {({ event }) => `${event.data?.title} · ${event.data?.owner}`} </Calendar.TimedEvents> </Calendar.DayColumns> </Calendar.TimeGrid> </Calendar.Root> )