Recurring events (RRULE) — kloq React calendar

Three series, stored as three events. Pick one above the grid and the row under it shows the same rule in plain English, the rrule string as it sits on the CalEvent, and the next time it fires. Wednesday's standup has already been moved once, so it is drawn from a detached event rather than the series.

Edit the selected rule with the builder — the grid re-expands on every change. Then drag any instance: kloq asks whether you meant this event, this and following, or all of them.

liveRecurring events (RRULE)

StandupSprint reviewPayday

Every weekdayFREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FRnext · —

All day

"use client";

import { useState, useSyncExternalStore } from "react";
import {
  Kloq,
  RRuleBuilder,
  describeRRule,
  formatEventWhen,
  formatInstant,
  nextOccurrence,
  parseInstant,
  useIsClient,
  useKloqStore,
} from "kloq";
import { SegmentedControl, SegmentedControlItem } from "@/components/ui/segmented-control";
import { Bar } from "../parts";
import { SERIES } from "./data";

const MASTERS = SERIES.filter((e) => e.rrule).map((e) => e.id);

function SeriesPanel() {
  const store = useKloqStore();
  const events = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getServerSnapshot);
  const isClient = useIsClient();
  const [selectedId, setSelectedId] = useState(MASTERS[0]);

  const masters = MASTERS.map((id) => events.find((e) => e.id === id)).filter((e) => e !== undefined);
  const selected = masters.find((e) => e.id === selectedId);
  const now = isClient ? new Date() : null;
  const next = selected && now ? nextOccurrence(selected, formatInstant(now)) : null;

  return (
    <>
      <Bar>
        <SegmentedControl
          fill
          size="sm"
          className="max-w-80"
          aria-label="Series"
          value={selectedId}
          onValueChange={setSelectedId}
        >
          {masters.map((e) => (
            <SegmentedControlItem key={e.id} value={e.id}>
              {e.title}
            </SegmentedControlItem>
          ))}
        </SegmentedControl>
        {selected ? (
          <RRuleBuilder
            value={selected.rrule}
            date={new Date(parseInstant(selected.start))}
            onChange={(rule) => store.update(selected.id, { rrule: rule })}
            className="w-72 max-w-full"
          />
        ) : null}
      </Bar>
      {selected ? (
        <Bar className="gap-y-1">
          <span className="text-foreground">{selected.rrule ? describeRRule(selected.rrule) : "Does not repeat"}</span>
          <span className="min-w-0 wrap-anywhere">{selected.rrule ?? "—"}</span>
          <span className="tabular-nums">
            next ·{" "}
            {next && now ? formatEventWhen({ ...selected, start: next.start, end: next.end }, now) : "—"}
          </span>
        </Bar>
      ) : null}
    </>
  );
}

export default function RecurringEventsExample() {
  return (
    <div className="@container flex flex-col">
      <div className="h-136">
        <Kloq defaultEvents={SERIES} persistence={false} designMode={false} storage={false}>
          <SeriesPanel />
          <Kloq.Toolbar />
        </Kloq>
      </div>
    </div>
  );
}

import { instantAt, resolveView, toDateOnlyString, type CalEvent } from "kloq";

/** Three series anchored on the Monday-start week containing `now`, plus one detached occurrence. */
export function buildSeries(now: Date = new Date()): CalEvent[] {
  const week = resolveView("week", 1, now);
  const at = (day: number, hour: number, minute = 0) => instantAt(week, day, hour * 60 + minute);
  const payday = new Date(now.getFullYear(), now.getMonth(), 25);
  const wednesdayStandup = at(2, 9);

  return [
    {
      id: "standup",
      title: "Standup",
      color: "blue",
      rrule: "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR",
      start: at(0, 9),
      end: at(0, 9, 15),
      // Wednesday's instance was moved — it lives below as its own event
      exdates: [wednesdayStandup],
    },
    {
      id: "standup-wed",
      title: "Standup · moved",
      color: "blue",
      start: at(2, 11),
      end: at(2, 11, 15),
      recurrenceId: wednesdayStandup,
    },
    {
      id: "review",
      title: "Sprint review",
      color: "violet",
      rrule: "FREQ=WEEKLY;INTERVAL=2;BYDAY=TH",
      start: at(3, 14),
      end: at(3, 15),
    },
    {
      id: "payday",
      title: "Payday",
      color: "emerald",
      allDay: true,
      busy: false,
      rrule: "FREQ=MONTHLY;BYMONTHDAY=25",
      start: toDateOnlyString(payday),
      end: toDateOnlyString(new Date(payday.getFullYear(), payday.getMonth(), 26)),
    },
  ];
}

export const SERIES = buildSeries();

"use client";

import type { ComponentProps } from "react";
import { ChevronLeft, ChevronRight } from "lucide-react";
import { formatViewTitle, useIsClient, useKloq } from "kloq";
import { Button } from "@/components/ui/button";
import { cn } from "@/lib/utils";

/** The strip an example hangs its controls and readouts on; same box as `Kloq.Toolbar`. */
export function Bar({
  edge = "bottom",
  className,
  ...props
}: ComponentProps<"div"> & { edge?: "top" | "bottom" }) {
  return (
    <div
      {...props}
      className={cn(
        "flex min-h-11 shrink-0 flex-wrap items-center gap-x-4 gap-y-2 px-4 py-2.5 font-mono text-xs text-muted-foreground",
        edge === "bottom" ? "border-b" : "border-t",
        className,
      )}
    />
  );
}

export function Dot({ live, className, ...props }: ComponentProps<"span"> & { live?: boolean }) {
  return (
    <span
      aria-hidden
      {...props}
      className={cn(
        "size-1.5 shrink-0 rounded-full",
        live ? "bg-brand motion-safe:animate-pulse" : "bg-border",
        className,
      )}
    />
  );
}

/** Previous / next / today for a calendar whose view is fixed. Must render inside `<Kloq>`. */
export function Nav({ locale }: { locale?: string }) {
  const k = useKloq();
  const isClient = useIsClient();
  return (
    <div className="flex min-w-0 items-center gap-1">
      <Button variant="ghost" size="icon-xs" aria-label="Previous" onClick={() => k.step(-1)}>
        <ChevronLeft />
      </Button>
      <Button variant="ghost" size="icon-xs" aria-label="Next" onClick={() => k.step(1)}>
        <ChevronRight />
      </Button>
      <Button variant="ghost" size="xs" className={cn(k.atToday && "text-muted-foreground")} onClick={k.goToday}>
        Today
      </Button>
      <span className="ms-1 truncate text-sm font-medium text-foreground tabular-nums sm:text-xs">
        {isClient ? formatViewTitle(k.view, locale, { short: k.narrow }) : null}
      </span>
    </div>
  );
}

usesrruledescribeRRulenextOccurrenceRRuleBuilder

How it works

A series is one event with an rrule — the RFC 5545 value without its RRULE: prefix. data.ts seeds FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR, FREQ=WEEKLY;INTERVAL=2;BYDAY=TH and an all-day FREQ=MONTHLY;BYMONTHDAY=25, all inside the subset the built-in expandRecurrence handles. See Recurrence for the frequencies and by-parts it models.
The moved Wednesday instance is two fields: exdates on the master (the occurrence start that no longer draws) and recurrenceId on the detached event (the occurrence it replaces). That is exactly what "change this event" writes when you drag one instance.
describeRRule(rule) renders the plain-English line; nextOccurrence(event, from) finds the next instance strictly after an instant. Both are pure and take the rule as a string or as parseRRule output.
RRuleBuilder is the panel's recurrence control, standalone. It takes the rule as value, the series' start as date (presets like "the first Thursday" derive from it) and commits through onChange; SeriesPanel writes the new rule with store.update from useKloqStore.
SeriesPanel is a child of <Kloq>, so it renders above the surface and can read the store with useSyncExternalStore(store.subscribe, store.getSnapshot). The "next" readout is gated on useIsClient() because it depends on the clock and must not hydrate.
Dragging, resizing or deleting an instance opens the built-in RecurrenceScopeDialog; the chosen scope becomes a RecurrencePlan from editOccurrence / deleteOccurrence and is applied as one batch, so undo reverts the whole answer. On the first occurrence "this and following" is the same as "all", and the dialog offers only two choices.

Take it further

Pass a controlled events array and the same drags arrive through onEventsChange as plain data — see Controlled state. A rule the builder cannot express (BYWEEKNO, several BYMONTHDAY values) is never rewritten: it shows as a read-only "Custom rule" chip, and registerRecurrenceEngine lets a richer engine expand it.