ChronousDocumentation

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
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.

Running here
typescript
const standup = {
  id: 'standup',
  start: '2026-03-16T09:00',
  duration: 'PT15M',
  recurrence: { rule: 'FREQ=WEEKLY;BYDAY=MO,WE,FR' },
}
More rules
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 start is the anchor. An anchor the rule does not match is not an instance: FREQ=WEEKLY;BYDAY=MO on 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.

typescript
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'],
  },
}
Running here

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.

typescript
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 },
    ],
  },
}
Running here

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.

typescript
// 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.