Guides
Recurrence
RRULE, extra dates, exceptions and overrides — expanded only for the range on screen.
A series
An event that carries recurrence is a series. Building a calendar expands it into instances, and only for the range asked for — an unbounded rule is never walked past the last day on screen.
type RecurrenceInput<TData = unknown> = { rule?: string dates?: string[] exceptions?: string[] overrides?: RecurrenceOverride<TData>[] } type RecurrenceOverride<TData = unknown> = { recurrenceId: string cancelled?: boolean start?: string end?: string duration?: string data?: TData }
The rule
rule is an RFC 5545 RRULE, with or without the RRULE: prefix. Supported parts are FREQ, INTERVAL, COUNT, UNTIL, BYDAY (with ordinals such as -1FR), BYMONTHDAY, BYMONTH, BYSETPOS and WKST. Unsupported parts or combinations throw InvalidRecurrenceError when Temporal is available. In Date fallback, an unreadable rule logs a warning and only the original and explicit dates are shown; see Temporal & Safari.
const standup = { id: 'standup', start: '2026-03-16T09:00', duration: 'PT15M', recurrence: { rule: 'FREQ=WEEKLY;BYDAY=MO,WE,FR' }, }
const monthly = { rule: 'FREQ=MONTHLY;BYDAY=-1FR' } const fortnightly = { rule: 'FREQ=WEEKLY;INTERVAL=2;COUNT=12' } const yearly = { rule: 'FREQ=YEARLY;BYMONTH=9;BYMONTHDAY=1;UNTIL=20300901T000000Z' }
- The event’s own
startis the anchor. An anchor the rule does not match is not an instance:FREQ=WEEKLY;BYDAY=MOon a Tuesday starts the following Monday. - Every instance keeps the wall clock and the wall length of the series, so a 09:00 meeting stays at 09:00 through a DST change.
Extra dates and exceptions
dates adds starts the rule does not produce, each with its own time of day. exceptions removes instances by their start — and COUNT is counted before they are removed, exactly as RFC 5545 asks.
const standup = { id: 'standup', start: '2026-03-16T09:00', duration: 'PT15M', recurrence: { rule: 'FREQ=WEEKLY;BYDAY=MO', dates: ['2026-03-19T11:00'], exceptions: ['2026-03-23T09:00'], }, }
Overrides
overrides replaces one instance, or drops it with cancelled. An override with no end or duration keeps the length of the series, and one that moves an instance into the range brings it into view.
const standup = { id: 'standup', start: '2026-03-16T09:00', duration: 'PT15M', recurrence: { rule: 'FREQ=WEEKLY;BYDAY=MO', overrides: [ { recurrenceId: '2026-03-30T09:00', start: '2026-03-30T10:00', duration: 'PT1H' }, { recurrenceId: '2026-04-06T09:00', cancelled: true }, ], }, }
What an instance looks like
An instance is a full event. Its id combines the series id, __, and the occurrence’s recurrenceId. It also carries seriesId and recurrenceId; a plain event has neither.
// A generated instance carries its series identity: { id: 'standup__2026-03-16T09:00:00+02:00', seriesId: 'standup', recurrenceId: '2026-03-16T09:00:00+02:00', } // A plain event has neither seriesId nor recurrenceId.