Event recurrence

ℹ️ Important note before getting started

This plugin enables you to create recurring events according to the iCalendar specification (opens in a new tab). Please note, however, that this plugin only offers a partial implementation of the specification. There are 2 reasons for this:

Some rules just haven't been implemented yet. If there is a rule that you would like to see implemented, and you think this rule could be updated in a predictable way using drag & drop or resize, please open an issue on GitHub.
Some iCalendar rules don't make sense in an interactive calendar. Consider for example FREQ=MONTHLY;BYDAY=1SU,4TH; COUNT=20 where dragging one occurrence might offset the other occurrences in a non-symmetrical way, which might not have been intended when creating the rule.

If you need an almost full implementation of the iCalendar spec, you can use the rrule (opens in a new tab) library instead of this plugin. However, this only works if you're merely using the calendar to display events. If you want to use interactive features like drag & drop or resizing, you cannot use the external rrule library.

Installation

npm install @schedule-x/event-recurrence

Usage

import { createEventRecurrencePlugin } from "@schedule-x/event-recurrence";
 
const calendar = createCalendar({
  // ... other config options
  plugins: [
    createEventRecurrencePlugin()
  ],
  events: [
    {
      id: 123,
      title: 'Bi-Weekly Event Monday and Wednesday',
      start: '2024-02-05 14:00',
      end: '2024-02-05 15:00',
      rrule: 'FREQ=WEEKLY;INTERVAL=2;BYDAY=MO,WE;UNTIL=20240229T235959'
    },
    {
      id: 456,
      title: 'Weekly Event on 4 occasions',
      start: '2024-02-03',
      end: '2024-02-03',
      rrule: 'FREQ=WEEKLY;COUNT=4'
    },
    {
      id: 789,
      title: 'Daily event 5 times',
      start: '2024-02-05 12:00',
      end: '2024-02-05 13:55',
      rrule: 'FREQ=DAILY;COUNT=5',
      calendarId: 'personal',
    },
    {
      id: 121314,
      title: 'Daily event mo-fr 10 times',
      start: '2024-02-05 12:00',
      end: '2024-02-05 13:55',
      rrule: 'FREQ=DAILY;COUNT=10;BYDAY=MO,TU,WE,TH,FR',
      calendarId: 'work',
    },
    {
      id: 141617,
      title: 'Monthly event on the 7th 5 times',
      start: '2024-02-07 16:00',
      end: '2024-02-07 17:55',
      rrule: 'FREQ=MONTHLY;COUNT=5',
    },
    {
      rrule: 'FREQ=YEARLY;COUNT=5',
      title: 'Event on the 8th of February for 5 years',
      start: '2024-02-08 16:00',
      end: '2024-02-08 17:55',
      id: 181920
    }
  ]
});

Supported rules

Rule	Supported values	Required
FREQ	`DAILY`, `WEEKLY`, `MONTHLY` or `YEARLY`	Yes
COUNT	Number	No
INTERVAL	Number	No
BYDAY - compatible with `DAILY` and `WEEKLY`	`MO`, `TU`, `WE`, `TH`, `FR`, `SA`, `SU`	No
BYMONTHDAY - compatible with `MONTHLY`	Positive integer 1-31	No
UNTIL	Floating date (opens in a new tab), for example `20240101` or date-time (opens in a new tab) `20240101T120000`	No

Events facade

When using this plugin, you should no longer use the normal events facade like calendar.events.add(...). Instead, you can now interact with the events such as:

 
const recurrencePlugin = createEventRecurrencePlugin();
const calendar = createCalendar({
  // ... other config options
  plugins: [
    recurrencePlugin
  ],
});
 
// Add an event
recurrencePlugin.eventsFacade.add({
  id: 1,
  title: 'New event',
  start: '2024-02-05 14:00',
  end: '2024-02-05 15:00',
  rrule: 'FREQ=WEEKLY;COUNT=3'
});
 
// Update
recurrencePlugin.eventsFacade.update({
  id: 1,
  title: 'New event',
  start: '2024-02-05 14:00',
  end: '2024-02-05 15:00',
  rrule: 'FREQ=WEEKLY;COUNT=10'
})
 
// Get one event with id 123
const event = recurrencePlugin.eventsFacade.get(123);
 
// Get all
const events = recurrencePlugin.eventsFacade.getAll();
 
// Remove an event with id 123
recurrencePlugin.eventsFacade.remove(123);

Calendar Controls Scroll Controller