Guides
Views & ranges
Day, week, days, month and agenda from one range object, and the slot rows a DST transition lands in.
The range
A range turns an anchor date into the days a calendar draws, and the rows it draws them on. It is a plain object you own; Chronous never changes it.
type CalendarRange = { view: 'day' | 'week' | 'days' | 'month' | 'agenda' currentDate: string timeZone: string weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 dayCount?: number slotMinutes?: number disambiguation?: Disambiguation }
The five views
Choose a date with currentDate, then choose how much of the calendar to show:
day— shows only the date you chose.week— shows the whole week containing that date, from Monday to Sunday by default.days— shows seven days starting on the date you chose. Unlikeweek, it does not go back to Monday.month— shows the month containing that date. It also includes a few dates from the previous or next month so every row has a full week.agenda— shows events as a list, covering thirty days starting on the date you chose.
Want a shorter or longer range? Set dayCount for days or agenda. To start weeks on a different weekday, set weekStartsOn.
Preparing the calendar example…
import type { CalendarRange } from '@midstem/chronous-react' const ranges: CalendarRange[] = [ // the anchor date itself { view: 'day', currentDate: '2026-03-25', timeZone: 'Europe/Kyiv' }, // Monday 23 to Sunday 29 — the week that contains the 25th { view: 'week', currentDate: '2026-03-25', timeZone: 'Europe/Kyiv' }, // seven days from the anchor: March 25 to 31; dayCount can override the default { view: 'days', currentDate: '2026-03-25', timeZone: 'Europe/Kyiv' }, // March, padded out to whole weeks { view: 'month', currentDate: '2026-03-25', timeZone: 'Europe/Kyiv' }, // the next thirty days as a list { view: 'agenda', currentDate: '2026-03-25', timeZone: 'Europe/Kyiv' }, ] // Pass a range to Calendar.Root or useCalendar to render this view.
Slots
A time grid is built for day, week and days; month and agenda carry no slots. Slots are wall-clock rows: a day has ceil(1440 / slotMinutes) of them, with a possibly shorter final row.
48 rows cover the day. The highlighted 09:30 row starts at minute 570 after midnight.
import { createCalendarComponents } from '@midstem/chronous-react' import type { CalendarRange, EventInput } from '@midstem/chronous-react' import { useState } from 'react' type EventData = { title: string } const Calendar = createCalendarComponents<EventData>() const INITIAL: CalendarRange = { view: 'week', currentDate: '2026-03-18', timeZone: 'Europe/Kyiv', slotMinutes: 30, } const EVENTS: EventInput<EventData>[] = [ { id: 'standup', start: '2026-03-18T09:00', end: '2026-03-18T09:30', data: { title: 'Standup (30m)' }, }, { id: 'planning', start: '2026-03-18T10:00', end: '2026-03-18T11:30', data: { title: 'Sprint planning' }, }, { id: 'sync', start: '2026-03-19T11:30', end: '2026-03-19T12:00', data: { title: 'Quick sync (30m)' }, }, ] export const Slots = (): JSX.Element => { const [range] = useState<CalendarRange>(INITIAL) return ( <Calendar.Root className="flex flex-col min-w-[660px] h-[600px] text-[#d8e5ff] bg-[#020013] border border-white/15 rounded-xl overflow-hidden" range={range} events={EVENTS} locale="en-GB" gutterWidth="56px" > <Calendar.Header className="border-b border-white/15"> <Calendar.DayHeadings className="py-2 text-center text-[13px] border-l border-white/5"> {({ weekdayLabel, dayLabel }) => ( <> <span>{weekdayLabel}</span> <strong>{dayLabel}</strong> </> )} </Calendar.DayHeadings> </Calendar.Header> <Calendar.TimeGrid className="flex-1 pt-2.5" hourHeight={48} scrollToHour={8} > <Calendar.TimeAxis> <Calendar.TimeLabels className="right-2 text-[10px] text-[#8d8da0]" /> </Calendar.TimeAxis> <Calendar.DayColumns className="border-l border-white/5"> <Calendar.TimeSlots className="border-t border-white/5" /> <Calendar.NowMarker className="border-t-2 border-[#e67a56]" /> <Calendar.TimedEvents as="button" className="line-clamp-3 px-1.5 py-[3px] text-[11px] leading-[13px] text-left text-[#0a0722] bg-[#aa90f8] rounded-md overflow-hidden cursor-pointer border-0" > {({ event, box }) => ( <span className={ box.minutes <= 30 ? 'inline-flex items-center gap-1 font-semibold whitespace-nowrap' : 'font-semibold' } > {event.data?.title} {box.continuesAfter && ' ↓'} </span> )} </Calendar.TimedEvents> </Calendar.DayColumns> </Calendar.TimeGrid> </Calendar.Root> ) }
A DST transition is absorbed by its row
Rows are placed by wall-clock time and sized by elapsed time. A DST transition can make a row longer than its label or create a zero-length row for a skipped time. No row is negative, and the day’s rows add up to its real elapsed length.
Both days still have 24 wall-clock rows. The missing hour takes 0 real minutes; the repeated hour takes 120.
import { buildCalendar } from '@midstem/chronous-react' import type { CalendarRange } from '@midstem/chronous' const dayRange = (currentDate: string): CalendarRange => ({ view: 'day', currentDate, timeZone: 'Europe/Kyiv', }) // The night Kyiv loses an hour: the 03:00 row runs none. const spring = buildCalendar(dayRange('2026-03-29'), []).days[0] console.log(spring.slots[3].minutes) // 0 console.log(spring.slots.length) // 24 console.log(spring.minutes) // 1380 — a 23-hour day // The night it gains one: the same row runs two hours. const autumn = buildCalendar(dayRange('2026-10-25'), []).days[0] console.log(autumn.slots[3].minutes) // 120 console.log(autumn.slots.length) // 24 console.log(autumn.minutes) // 1500
disambiguation is what the events are read with and is never applied to a row — leave it alone unless a schedule has to round one way by policy. A currentDate or time zone that cannot be read, a slotMinutes outside 1 to 1440 or a dayCount below one throws InvalidRangeError.