Get Started
Get Started
One package, no stylesheet and no setup — install it, describe the range and draw your first week.
Installation
Chronous ships as a set of headless components and hooks and nothing else — no bundled CSS, no peer plugins for time zones or recurrence. React 18 and React 19 are both supported.
Install the React package alongside temporal-polyfill:
npm install @midstem/chronous-react temporal-polyfill
The React adapter bundles the engine and re-exports its API, so one install is enough. Install @midstem/chronous separately only when using the engine outside React.
Chronous relies on the modern JavaScript Temporal API for exact time zones, DST transitions, and date math. Native support depends on the browser or runtime version; check globalThis.Temporalbefore relying on it.
Safari and older runtimes do not yet provide native Temporal. If Temporal is absent, Chronous automatically uses an internal Date and Intl fallback with a console warning. To ensure exact DST and recurrence behavior, provide temporal-polyfill from your application entry module:
// Application entry module (e.g. index.ts or main.tsx) import 'temporal-polyfill/global' import { Calendar } from '@midstem/chronous-react'
For detailed information on why Temporal is required, and how to conditionally load the polyfill only where Temporal is missing, see Temporal & Safari.
Frameworks
The engine is headless and framework agnostic. Each adapter exposes the same time model and layout calculations under the idioms of your framework. Pick one here or in the selector above, and the whole of this documentation follows it.
Your first calendar
Wiring is a single hook or the compound Calendar components. A calendar is described by two things: a range that says what to draw, and the events to draw in it. The rendered markup is yours: you choose its elements and classes.
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> )
The three inputs
- The range — the view, the date the calendar is on and the time zone it is read in. It is yours to hold: a router, a query string or state all work, because the engine never mutates it.
- The events — plain objects of ISO-8601 strings, with your own payload under
data. An event can recur, span days or be all-day. - Your markup — renders compound parts and manages event geometry.
Primitives and engine
The components are built on two hooks, and both are exported. Reach for useCalendar when you would rather walk the layout yourself: it hands back the same plain object, with the errors caught rather than thrown.
import { useCalendar } from '@midstem/chronous-react' import type { CalendarDay, 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' }, ] const Column = ({ day }: { day: CalendarDay }) => ( <li> {day.date} — {day.boxes.length} events </li> ) export const Board = () => { const { calendar, error } = useCalendar(range, events) if (error) return <p>{error.message}</p> if (!calendar) return null return ( <ul> {calendar.days.map(day => ( <Column key={day.date} day={day} /> ))} </ul> ) }
Where to go next
- Views & ranges — day, week, month and agenda from the one range object.
- Components — the rules that cover the layout components and directives.
- Temporal & Safari — providing Temporal on browsers without native support.
- Examples — a week, a month and an agenda, each with the code that produced it.
- Playground — test views, events, and options interactively in your framework.