Guides
Events
An event is ISO-8601 strings: what start, end, duration and allDay mean, and how a time zone is read.
The shape
Event scheduling fields use ISO-8601 strings rather than Date or Chronous date objects. Your own payload rides along under data, typed, and comes back unchanged on every box and bar.
type EventInput<TData = unknown> = { id: string start: string end?: string duration?: string allDay?: boolean timeZone?: string recurrence?: RecurrenceInput<TData> data?: TData }
import { Calendar } from '@midstem/chronous-react' import type { CalendarRange, EventInput } from '@midstem/chronous-react' const range: CalendarRange = { view: 'week', currentDate: '2026-03-18', timeZone: 'Europe/Kyiv', } const events: EventInput[] = [ { id: 'standup', start: '2026-03-18T09:00', duration: 'PT30M' }, ] export const Board = () => ( <Calendar.Root range={range} events={events} locale="en-GB"> <Calendar.Header> <Calendar.DayHeadings className="heading" /> </Calendar.Header> <Calendar.TimeGrid hourHeight={48}> <Calendar.TimeAxis> <Calendar.TimeLabels className="tick" /> </Calendar.TimeAxis> <Calendar.DayColumns className="column"> <Calendar.TimeSlots className="line" /> <Calendar.TimedEvents className="event" /> </Calendar.DayColumns> </Calendar.TimeGrid> </Calendar.Root> )
How long an event is
endwins overduration; with neither, a timed event has zero length.durationis an ISO-8601 duration. Date units are calendar arithmetic —P1Dkeeps the wall clock across a DST transition — while clock units are exact, soPT4His always four real hours.- An event that ends before it starts throws
InvalidEventError, carrying the offendingeventId.
const events = [ { id: 'workshop', start: '2026-03-29T00:30', duration: 'PT4H' }, { id: 'sprint', start: '2026-03-29T00:30', duration: 'P1D' }, ]
All-day events
An event is all-day when allDay says so, or when its dates carry no time. All-day events are plain dates with no zone attached, and their end is exclusive.
const events = [ // End is exclusive: 16, 17 and 18 March { id: 'offsite', start: '2026-03-16', end: '2026-03-19' }, { id: 'holiday', start: '2026-03-20', end: '2026-03-20' }, { id: 'launch', start: '2026-03-17T09:00', allDay: true }, ]
In day, week, and days views, all-day events appear in bars above the time grid. Month and agenda views place them in their own layouts — Layout & lanes covers how the bars are packed.
Time zones
Times are read in the calendar’s time zone unless the event carries its own — that is how a Kyiv office schedule stays correct when it is opened from Berlin.
const events = [ { id: 'office-hours', start: '2026-03-18T11:00', duration: 'PT1H' }, { id: 'tokyo-sync', start: '2026-03-18T16:00', duration: 'PT1H', timeZone: 'Asia/Tokyo' }, ]