Skip to content

Recurrence

An event with an rrule is a series: its start is the first occurrence, its length every occurrence’s length, and the rule — the RFC 5545 rule calendars exchange in .ics files — says when it comes back.

The rules engine is loaded once, by one import; without it an event with an rrule is left out, with the problem recurrence-not-loaded (@dzcalendar/ical brings it itself):

import '@dzcalendar/core/recurrence';
import { createCalendar } from '@dzcalendar/dom';
createCalendar(element, {
timeZone: 'Europe/Paris',
events: [
// Mondays and Wednesdays, 08:00–10:00.
{ id: 'rounds', title: 'Rounds', start: '2026-10-19T08:00[Europe/Paris]', duration: { hours: 2 }, rrule: 'FREQ=WEEKLY;BYDAY=MO,WE' },
// The second Tuesday of each month, ten times.
{ id: 'board', title: 'Board', start: '2026-10-13T18:00[Europe/Paris]', duration: { hours: 1 }, rrule: 'FREQ=MONTHLY;BYDAY=TU;BYSETPOS=2;COUNT=10' },
// Every day of the week, all day, until the end of November.
{ id: 'duty', title: 'On duty', start: '2026-10-19', allDay: true, rrule: 'FREQ=DAILY;UNTIL=20261130' },
],
});

The whole of RFC 5545’s rule is read: every FREQ from YEARLY to SECONDLY, INTERVAL, COUNT or UNTIL, and every BY… part (BYDAY with its positions — 2TU, -1FR —, BYMONTHDAY, BYSETPOS, BYWEEKNO…). Several rules in an array make one series of their union. The occurrences are computed for the weeks shown, never stored ahead: a series without an end is fine.

{
id: 'rounds',
title: 'Rounds',
start: '2026-10-19T08:00[Europe/Paris]',
duration: { hours: 2 },
rrule: 'FREQ=WEEKLY;BYDAY=MO,WE',
exdate: ['2026-11-11T08:00[Europe/Paris]'], // a holiday: not that Wednesday
rdate: ['2026-11-13T08:00[Europe/Paris]'], // the Friday instead
}

An exdate names an occurrence by its start, written as the series writes it; an all-day series takes dates ('2026-11-11'). A single occurrence changed — moved, renamed — is an event of its own linked to the series: seriesId (the series’ id) and recurrenceId (the start of the occurrence it replaces), given in the same list — or the same delivery of a source — as its series; alone, it is shown as a plain event, with an orphan-override warning. That is what iCalendar’s RECURRENCE-ID is, and what the calendar makes itself when a person changes “this occurrence”.

A series lives on the wall clock of its zone. “Every Monday at 08:00 in Paris” is at 08:00 on the Monday after the clocks go back too — 07:00 UTC in winter, 06:00 in summer — and, drawn in New York, it moves by an hour for the weeks when Europe and America do not change on the same Sunday. That is what a person means by “every Monday at 8”, and what the other calendars do.

  • An occurrence whose wall time falls in the hour skipped in spring (02:30 in Paris on the last Sunday of March) is moved forward, to 03:30.
  • In the hour repeated in autumn, it takes the first 02:30.
  • HOURLY, MINUTELY and SECONDLY count hours that pass instead: “every two hours” stays two hours apart across the change.

An occurrence is known by its original start, offset included (2026-10-25T02:30:00+02:00[Europe/Paris]): the two 02:30s of the night the clocks go back are two occurrences, never one — a series counting hours (HOURLY) has both; a daily one, as said above, the first.

Editing an occurrence: this, following, all

Section titled “Editing an occurrence: this, following, all”

When a person drags, resizes or deletes an occurrence, the calendar asks how far the change reaches — try it: drag one of the Rounds to another day.

  • This event — only that occurrence changes; the series skips it, or holds it where it was moved.
  • This and following events — the series is cut there: before, unchanged; from it on, the change. A series of ten keeps ten in all; one ending on a date keeps its date — moved with the days when the change moves the days.
  • All events — every occurrence changes the same way. Moved from Monday 08:00 to Tuesday 09:00, the Mondays and Wednesdays become Tuesdays and Thursdays at 09:00 — still 09:00 on the wall after the clocks change. The changed occurrences and the dates taken out move with it.

Undo takes back exactly what was there, both halves of a cut included. To ask in your own way, or to decide without asking, give chooseScope a function returning 'this', 'following', 'all', or null to cancel.

The event commands take a scope, and an occurrence is named by the key of the instance a callback gave you (series@originalStart):

import '@dzcalendar/core/recurrence';
import { createCalendar } from '@dzcalendar/dom';
const calendar = createCalendar(element, {
timeZone: 'Europe/Paris',
events: [{ id: 'rounds', title: 'Rounds', start: '2026-10-19T08:00[Europe/Paris]', duration: { hours: 2 }, rrule: 'FREQ=WEEKLY;BYDAY=MO,WE' }],
onEventClick: (instance) => {
if (instance.origin !== 'occurrence' || instance.event.allDay) return;
// This one only: an hour later.
calendar.run({ type: 'event.move', id: instance.key, start: instance.event.start.add({ hours: 1 }) });
},
});
// The series' id with the occurrence's original start, and a scope.
calendar.run({ type: 'event.update', id: 'rounds', key: '2026-11-04T08:00[Europe/Paris]', scope: 'following', patch: { title: 'Rounds (new wing)' } });
Command Does
event.move, event.resize, event.update, event.delete With scope ('this', 'following', 'all') and key — an instance key alone is 'this'; a key without its offset, in the hour repeated, is the first
series.delete The whole series, every occurrence and every change
series.split “This and following” without a gesture: the series cut at an occurrence, a patch from there
series.rule A new rrule for the whole series, its exceptions kept; null stops it repeating
event.repeat A single event made a series, the same id

A whole series cannot switch between all-day and timed (invalid-edit); one occurrence can, without being asked.

FREQ=WEEKLY;INTERVAL=2;BYDAY=MO,SU depends on the day a week starts. A rule created in the calendar — a person’s “repeats” in the editor, event.create or event.repeat run by your code — gets WKST written in — the calendar’s first day of the week (firstDay, else the locale’s) — so it means the same anywhere it is read. A rule read from elsewhere without WKST is read with Monday, as RFC 5545 and the other calendars read it; series.rule keeps the series’ own.