API reference

Every export of the copied kloq source — the root module, themes, settings and design-mode — grouped by area.

Every export, grouped by area — the component and its chrome, then the pure layers underneath, then the three companion modules. Types ship alongside the values they describe.

<Kloq> props

proptype · description
view?
"day" | "week" | "month" | "agenda" | "year" | "timeline" | number

Controlled view. A number is an n-day span (2–14). Pair with onViewChange.

defaultView?
KloqViewdefault "week"

Uncontrolled starting view. Ignored when view is set.

onViewChange?
(view: KloqView) => void

Fired whenever something asks to change the view, controlled or not.

date?
Date

Controlled anchor date. Navigation only reports via onDateChange.

defaultDate?
Date

Uncontrolled starting anchor; defaults to today.

onDateChange?
(date: Date) => void

Fired whenever something asks to move the anchor date.

events?
CalEvent[]

Controlled events. Switches the internal store off — pair with onEventsChange.

onEventsChange?
(events: CalEvent[]) => void

The full next event list on every committed change (controlled mode).

defaultEvents?
CalEvent[]default sample events

Uncontrolled starting events. Omit for the sample events; pass [] to start empty.

lanes?
readonly Lane[]default []

Rows for view="timeline". Ignored by every other view. Empty by default — nothing renders without lanes.

persistence?
false | PersistenceAdapterdefault localStorage

Uncontrolled persistence: false is ephemeral, omit is localStorage, or bring an adapter.

storage?
StorageSettingdefault "kloq"

Everything kloq keeps in localStorage. false keeps it in memory; a string namespaces the keys.

onCommit?
OnCommit

Optimistic seam — called on every committed change; a rejected promise reverts it.

onUndo?
() => void

Controlled-mode undo — ⌘Z calls it.

onRedo?
() => void

Controlled-mode redo — ⇧⌘Z calls it.

onRangeChange?
(start: Date, end: Date) => void

The visible range changed — [start, end). Fires once on mount, then on every view or date change.

rangePadding?
number | { before: number; after: number }default 0

Days to widen the range onRangeChange reports.

density?
"comfortable" | "compact"default "comfortable"

Hour height, event type size and padding together.

zoom?
numberdefault 4

Live zoom as an index into ZOOM_STEPS (0–10; 4 = 100%).

hourHeight?
number

px per hour, clamped to 8–480. Omit and density picks the base.

dayStartHour?
numberdefault 0

First hour the grid draws (0–23); with dayEndHour this clips the day.

dayEndHour?
numberdefault 24

Last hour the grid draws (exclusive).

snapMinutes?
numberdefault 15

Drag and keyboard snap grid.

snapFineMinutes?
numberdefault 5

Snap grid while ⌥ is held.

minEventMinutes?
numberdefault 15

Shortest event a resize can produce.

weekStartsOn?
0 | 1 | 2 | 3 | 4 | 5 | 6default 1

0 = Sunday … 6 = Saturday.

constraints?
KloqConstraints

Bounds (minDate / maxDate), a per-slot refusal and a per-event veto. Refused time draws as a hatch; every gesture honours it.

workingHours?
{ start: number; end: number } | falsedefault { start: 9, end: 17 }

Working-hours tint boundaries; false disables the tint.

showWeekNumbers?
booleandefault false

ISO 8601 week numbers in the gutter corner (time-grid views).

responsive?
ResponsiveSettingdefault true

Collapse a week to three days, then to one, as the box narrows. view is never rewritten.

locale?
stringdefault "en-US"

BCP 47 tag for every date and time label.

hour12?
boolean

Force a 12- or 24-hour clock; omit and the locale decides.

displayTimeZone?
string

Draw the calendar in this IANA zone instead of the browser's.

timeZones?
(string | TimeZoneColumn)[]

Extra gutter zone columns, in order.

designMode?
boolean | { hint?: boolean }default true

Figma-style design mode (⌥D). { hint: false } hides the hint bar.

commandPalette?
boolean | { commands?: string[] }default true

⌘K. false removes the binding and the menu; { commands } narrows the built-ins — spread BUILT_IN_COMMANDS and filter.

globalShortcuts?
booleandefault false

Let ⌘K / ⌘Z / ⌥D fire when focus is outside the calendar.

navigationKeys?
"range" | "day"default "range"

What ←/→ move by. PageUp / PageDown always step the range.

currentUserEmail?
string

Who "you" are. Enables RSVP, per-person conflicts and showDeclinedEvents.

showDeclinedEvents?
booleandefault true

Draw events you have declined.

keymap?
Keymap

Overrides for the remappable mnemonics.

theme?
string

Scope a theme to this calendar and its portals — no <html> attribute, no localStorage. Omit to follow the page (setTheme). See Theming.

scheme?
"light" | "dark"

Pin this calendar's colour scheme regardless of the page's .dark. Omit to follow the page.

components?
Partial<KloqComponents>

Slot overrides — swap any visual piece; the engine keeps the physics.

makeId?
() => stringdefault random UUID

Id factory for everything the calendar creates.

ssr?
booleandefault false

Render the event layer on the server too. Only hydration-safe with controlled events, a date and displayTimeZone.

laneAdapter?
LaneAdapterdefault byResourceId()

How an event maps onto a lane, for view="timeline". See Resources & lanes.

timelineWindow?
TimelineWindowConfig

The timeline's visible span and slot size — controlled (pass start and end) or derived from the anchor date. See Resource timeline.

onEventClick?
(event: CalEvent, placementId: string) => void

An event was clicked, not dragged.

onEventDoubleClick?
(event: CalEvent, placementId: string) => void

Double-click on an event; fires after onEventClick.

onSlotClick?
(slot: { start: Date; end: Date; allDay: boolean }) => void

An empty slot was clicked, snapped like drag-create.

onSelectionChange?
(events: CalEvent[]) => void

The selection changed, in reading order.

onTimeZonesClick?
() => void

The gutter-corner zone labels were pressed; providing it renders them as a button.

onCustomizeKeybinds?
() => void

"Customize shortcuts…" was pressed in the ? sheet.

Component & chrome

Configuration

Slots & store

Event model & instants

Attendees & conflicts

Commands, quick add, search, keyboard

Views, navigation & layout

Resource timeline

<Kloq> takes three more props for view="timeline", alongside KLOQ_PROPS above: lanes (readonly Lane[], empty by default — nothing renders without rows), laneAdapter (LaneAdapter, defaults to byResourceId()), and timelineWindow (TimelineWindowConfig, see Resource timeline for its two modes). The exports underneath:

Time zones, recurrence, ICS, reminders

These four areas have their own pages; the exports are enumerated there. Time zones: the full pure layer from wallClockIn to searchZones, plus MultiTimeZoneGutter and the authored-zone helpers. Recurrence: the RRULE library, the expansion seam, the this/following/all plans, RRuleBuilder and RecurrenceScopeDialog. ICS: toICS / downloadICS out, parseICS and its structural layer in. Reminders: normalization, descriptions and fire-time math from normalizeReminders to nextReminderAcross, plus the ReminderField control — kloq computes fire times, the host delivers.

Multi-calendar & accounts

@/components/kloq/lib/themes

@/components/kloq/settings

@/components/kloq/design-mode

Last updated