One component. The whole calendar.

01start here

Three steps to a calendar.

1. 1

   Install

   terminal

   $ npm install kloq

   React 19 and Tailwind v4 are assumed. Or land the whole calendar in your repo through the source registry.

   Installation →

2. 2

   Import the stylesheet once

   app/layout.tsx

   import "kloq/styles.css";

   In the root layout — CSS imported inside a page or component only reaches that route.

   Light and dark →

3. 3

   Give it a box

   app/page.tsx

   <div className="h-dvh">
     <Kloq />
   </div>

   <Kloq> is h-full. No height, no calendar — the one mistake everyone makes first.

   Quick start →

02the map

1. 01getting started

   4 pages
   • Overviewyou are hereOne React component and the manual for it — installing, configuring and customising kloq, with the calendar running live.
   • InstallationTwo ways in — the npm package, or the source registry that lands the whole calendar in your repo.
   • Quick startA working calendar in one component: container, toolbar, defaults, and where to go next.
   • PlaygroundEvery prop on knobs: a live calendar and a snippet that rewrites itself as you flip them.

2. 02examples

   18 pages
   • ExamplesSixteen ways to use one component — each a live calendar with the source beside it, grounded in the real API.
   • Booking calendarA Cal.com-style availability picker — busy time hatched and refused by constraints, click a free slot to book.
   • Team calendarTwo accounts, five calendars, colour inherited from the calendar — with a sidebar that toggles each one.
   • Room bookingFour meeting rooms as timeline lanes — drag to book, drag across rooms to reassign, drag an edge to resize.
   • Shift schedulerFive people, one week, as timeline lanes — drag to schedule, drag across rows to reassign a shift to someone else.
   • Conference agendaA public, read-only programme in 24-hour time with tracks as locations and a details sheet on click.
   • Calendar in an app layoutThe calendar as one route of a product — sidebar nav, a header built from useKloq(), and a container that gives it a real height.
   • Optimistic server syncEvery change is committed to a fake server with latency and a reject switch; a rejection springs the block back to where it was.
   • Lazy-load by date rangeA controlled calendar that only holds what onRangeChange has fetched, merged page by page, with edits written back to the server copy.
   • View and date in the URLControlled view and date mirrored into the query string, so a link opens the same week and the browser's back button steps the calendar.
   • Custom persistence adapterUncontrolled events saved through your own adapter — sessionStorage with a versioned payload and a per-tenant namespace, plus a tenant switcher.
   • ICS import and exportDrop a .ics feed onto the calendar, then export the visible week back out as a file.
   • Custom event renderingA deploy pipeline drawn with its own EventBlock — status stripe, progress bar, mono duration — with the engine contract honoured so drags and resizes still work.
   • Multiple time zonesDraw the grid in any zone, add London / New York / Tokyo gutter columns, and keep each event's authored zone.
   • Linked month and day viewsA month overview beside a day view, both controlled by the same date — click a day on the left, it opens on the right.
   • Recurring events (RRULE)Weekday standups, a fortnightly review and a monthly payday — as RRULE strings, expanded live, edited this / following / all.
   • Custom ⌘K commandsDomain commands in the palette, a remapped key, and a button that opens the shortcut sheet.
   • Natural-language event entryType "lunch with Sam tomorrow 1pm" into a box above the grid; the parser underlines what it understood and the event lands.

3. 03registry

   1 page
   • The registryThe source tier: the calendar and its add-on blocks, delivered by the shadcn CLI as licensed source.

4. 04core concepts

   8 pages
   • EventsCalEvent: the discriminated union on allDay, real instants, colors, attendees, and every optional field.
   • Controlled stateview, date and events as controlled or uncontrolled props, plus onRangeChange and controlled undo/redo.
   • PersistenceThe PersistenceAdapter contract, the localStorage default, and the versioned payload migration.
   • Optimistic syncThe onCommit seam: changes land instantly, rejections spring back. KloqChange, batching, and wiring a real API.
   • Views & navigationDay, week, n-day, month, agenda, year — what each shows, what prev/next step by, and the responsive collapse.
   • Resource timelineRooms, staff or machines as rows along a horizontal time axis — drag to book, drag across rows to reassign, drag an edge to resize.
   • Resources & lanesThe row-binding seam for the timeline — laneOf, assign, byResourceId, and why a row is whatever the host says it is.
   • ConstraintsRefuse time on the grid: bounds, per-date rules and per-event vetoes that every gesture honours.

5. 05customization

   4 pages
   • ThemingNineteen themes across three families, light and dark schemes inside every one, and a zero-flash SSR restore script.
   • SlotsTen swappable visual pieces with typed contracts. The engine, grid math and craft-bus stay fixed; overrides plug into them.
   • Toolbar & chromeKloq.Toolbar, Kloq.Nav, Kloq.Reset and useKloq() — the app bar as opt-in composable parts.
   • Settings dialogThe settings module — the optional preferences dialog, its KloqPreferences model, and the account helpers behind it.

6. 06interaction

   5 pages
   • Command palette⌘K ships with the component — an open command registry, whole-store event search, and a natural-language "move to…". Your commands rank alongside the built-ins.
   • KeyboardThe scoped keyboard layer — remappable mnemonics via the keymap prop, the ? sheet that can never lie, and what is deliberately fixed.
   • Quick addNatural-language event entry: parseQuickAdd, the grammar it understands, and the offsets that power the live underline.
   • Quick add inputThe ⌘K quick-add field as a standalone component: the live underline, the preview line, and a commit you own.
   • Design mode⌥D: a calendar-aware inspector, live spring tuning with slow motion, a pin tour, geometry overlays, and a contrast-scoring theme picker.

7. 07advanced

   4 pages
   • Time zonesdisplayTimeZone, extra gutter columns, per-event authored zones, and the pure Intl-backed zone layer.
   • RecurrenceRRULE on CalEvent, the expansion seam, occurrence placements, and this/following/all edit semantics.
   • ICS import & exporttoICS and downloadICS out, parseICS in — RFC 5545 both directions, pure, and never throwing.
   • API referenceEvery export of the copied kloq source — the root module, themes, settings and design-mode — grouped by area.

03examples

• Booking calendarA Cal.com-style availability picker: busy time hatched and refused by constraints, click a free slot to book.constraintsisSlotDisabledslotAllowed
• Team calendarTwo accounts, five calendars, colour inherited from the calendar — with a calendar list that toggles each one.registerCalendarAccountCalendarListcalendarId
• Optimistic server syncEvery change is committed to a fake server with latency and a reject switch; a rejection springs the block home.onCommitKloqChangedefaultEvents
• Custom event renderingA deploy pipeline drawn with its own EventBlock — status stripe, progress, and the engine contract honoured so drags still work.componentsEventBlockPropsregisterNode