ChronousDocumentation

Guides

Navigation

Next, previous, today and a view switch — a pure reducer, a hook over it and a toolbar around both.

The hook

useCalendarNavigation(range) returns the ranges to move to, and never sets state itself. Where the range lives is your decision — a router, a query string or useState all work the same.

React
import { useCalendarNavigation } from '@midstem/chronous-react'
import type { CalendarRange } from '@midstem/chronous-react'
import { useState } from 'react'

const INITIAL: CalendarRange = {
  view: 'week',
  currentDate: '2026-03-18',
  timeZone: 'Europe/Kyiv',
}

export const Controls = () => {
  const [range, setRange] = useState<CalendarRange>(INITIAL)
  const { next, prev, today, withView } = useCalendarNavigation(range)

  return (
    <nav>
      <button disabled={!prev} onClick={() => prev && setRange(prev)}>
        Back
      </button>
      <button disabled={!today} onClick={() => today && setRange(today())}>
        Today
      </button>
      <button disabled={!next} onClick={() => next && setRange(next)}>
        Forward
      </button>
      <button onClick={() => setRange(withView('month'))}>Month</button>

      <output>
        {range.view} · {range.currentDate}
      </output>
    </nav>
  )
}
  • A step moves by the period the range asks for: a day by one day, a week by seven, a span by its own length, and a month by one month anchored on the first — so a long month never drags the anchor backwards.
  • The weekday of the anchor survives a week step, which is what makes switching to day afterwards land where the reader was looking.
  • today is a function rather than a value because it depends on the wall clock: it is read at the click, in the calendar’s own zone.

The toolbar

Calendar.Toolbar wraps the hook and reports where to move to through onNavigate. The same function reaches its render prop as goTo, alongside a formatted title, so a toolbar of your own is a few buttons and nothing else.

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

const events: EventInput<EventData>[] = [
  {
    id: 'offsite',
    start: '2026-03-18',
    end: '2026-03-20',
    data: { title: 'Offsite' },
  },
  {
    id: 'standup',
    start: '2026-03-16T09:00',
    duration: 'PT30M',
    recurrence: { rule: 'FREQ=WEEKLY;BYDAY=MO,WE,FR' },
    data: { title: 'Standup' },
  },
  {
    id: 'planning',
    start: '2026-03-16T11:00',
    end: '2026-03-16T12:30',
    data: { title: 'Sprint planning' },
  },
  {
    id: '1on1',
    start: '2026-03-17T10:30',
    duration: 'PT45M',
    data: { title: '1:1 Sync' },
  },
  {
    id: 'review',
    start: '2026-03-18T14:00',
    end: '2026-03-18T15:30',
    data: { title: 'Design review' },
  },
  {
    id: 'pairing',
    start: '2026-03-18T14:30',
    end: '2026-03-18T16:00',
    data: { title: 'Pairing' },
  },
  {
    id: 'demo',
    start: '2026-03-19T15:00',
    duration: 'PT1H',
    data: { title: 'Product demo' },
  },
  {
    id: 'retro',
    start: '2026-03-20T16:00',
    duration: 'PT1H',
    recurrence: { rule: 'FREQ=WEEKLY;BYDAY=FR' },
    data: { title: 'Weekly retro' },
  },
]

export const Board = () => {
  const [range, setRange] = useState<CalendarRange>(INITIAL)

  return (
    <Calendar.Root
      className="calendar"
      range={range}
      events={events}
      locale="en-GB"
      gutterWidth="56px"
    >
      <Calendar.Toolbar className="toolbar" onNavigate={setRange}>
        {({ title, navigation, goTo }) => (
          <>
            <button
              disabled={!navigation.prev}
              onClick={() => navigation.prev && goTo(navigation.prev)}
            >
              ←
            </button>
            <strong>{title}</strong>
            <button
              disabled={!navigation.next}
              onClick={() => navigation.next && goTo(navigation.next)}
            >
              →
            </button>
          </>
        )}
      </Calendar.Toolbar>

      <Calendar.Header className="header">
        <Calendar.DayHeadings className="heading">
          {({ weekdayLabel, dayLabel }) => (
            <>
              <span>{weekdayLabel}</span> <strong>{dayLabel}</strong>
            </>
          )}
        </Calendar.DayHeadings>
      </Calendar.Header>

      <Calendar.AllDayRow
        className="all-day"
        minLanes={1}
        gutterCell={<span className="gutter-label">all-day</span>}
      >
        <Calendar.AllDayEvents className="bar">
          {({ event }) => event.data?.title}
        </Calendar.AllDayEvents>
      </Calendar.AllDayRow>

      <Calendar.TimeGrid className="grid" hourHeight={48} scrollToHour={8}>
        <Calendar.TimeAxis>
          <Calendar.TimeLabels className="tick" />
        </Calendar.TimeAxis>

        <Calendar.DayColumns className="column">
          <Calendar.TimeSlots className="line" />
          <Calendar.NowMarker className="now" />
          <Calendar.TimedEvents as="button" className="event">
            {({ event, box }) => (
              <>
                {event.data?.title}
                {box.continuesAfter && ' ↓'}
              </>
            )}
          </Calendar.TimedEvents>
        </Calendar.DayColumns>
      </Calendar.TimeGrid>
    </Calendar.Root>
  )
}