ChronousDocumentation

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
type EventInput<TData = unknown> = {
  id: string
  start: string
  end?: string
  duration?: string
  allDay?: boolean
  timeZone?: string
  recurrence?: RecurrenceInput<TData>
  data?: TData
}
Events in a calendar
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

  • end wins over duration; with neither, a timed event has zero length.
  • duration is an ISO-8601 duration. Date units are calendar arithmetic — P1D keeps the wall clock across a DST transition — while clock units are exact, so PT4H is always four real hours.
  • An event that ends before it starts throws InvalidEventError, carrying the offending eventId.
typescript
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.

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

Running here

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.

Running here
typescript
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' },
]