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
dayafterwards land where the reader was looking. todayis 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> ) }