Get Started

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

Chronous relies on the modern JavaScript Temporal API for exact time zones, DST transitions, and date math. Chrome and Edge (from 144) and Firefox (from 139) support Temporal natively.

Safari and older runtimes do not yet provide native Temporal, so the host application must supply temporal-polyfill. Import its global entry 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 so modern browsers like Google Chrome never download it, 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. Everything you can see below is markup you own — every part renders the tag you name and takes your class names.

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>
  )
}

Outside any UI library, it is one function call:

import { buildCalendar } from '@midstem/chronous'

const calendar = buildCalendar(
  { view: 'week', currentDate: '2026-03-18', timeZone: 'Europe/Kyiv' },
  [{ id: 'standup', start: '2026-03-18T09:00', duration: 'PT30M' }],
)

console.log(calendar.days.length) // 7
console.log(calendar.days[2].boxes.length) // 1 — Wednesday the 18th

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.