ChronousDocumentation

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
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. Unlike week, 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.

Same anchor · Wednesday 25 March 2026

Preparing the calendar example…

React
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.

Half-hour slots · 18 March 2026
09:00
09:00–09:30
30 min
09:30
09:30–10:00
30 min
10:00
10:00–10:30
30 min

48 rows cover the day. The highlighted 09:30 row starts at minute 570 after midnight.

Running here
Slots.tsx
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.

The 03:00 row in Europe/Kyiv
Spring forward
29 March 2026 · 23-hour day
02:00
60 min
03:00
0 min
04:00
60 min
Fall back
25 October 2026 · 25-hour day
02:00
60 min
03:00
120 min
04:00
60 min

Both days still have 24 wall-clock rows. The missing hour takes 0 real minutes; the repeated hour takes 120.

typescript
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.