NEWScheduling Assistant ✨
Docs
Calendar
Plugins
Event Recurrence

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:

  1. 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.
  2. 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. Here's an example (opens in a new tab) of how to do so. 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

RuleSupported valuesRequired
FREQDAILY, WEEKLY, MONTHLY or YEARLYYes
COUNTNumberNo
INTERVALNumberNo
BYDAY - compatible with DAILY and WEEKLYMO, TU, WE, TH, FR, SA, SUNo
BYMONTHDAY - compatible with MONTHLYPositive integer 1-31No
UNTILFloating date (opens in a new tab), for example 20240101 or date-time (opens in a new tab) 20240101T120000No
WKSTMO, TU, WE, TH, FR, SA, SUNo

exdate

You can exclude certain dates or date-times from a recurrence set using the exdate rule. For example:

const recurringEventWithExclusions = {
  id: 123,
  title: 'Weekly event',
  start: '2024-02-05 14:00',
  end: '2024-02-05 15:00',
 
  // will create a recurrence set of 3 events: 2024-02-05 14:00, 2024-02-26 14:00, 2024-03-04 14:00
  rrule: 'FREQ=WEEKLY;COUNT=5',
  exdate: [
    '2024-02-12 14:00',
    '2024-02-19 14:00'
  ]
}

Events service

When using this plugin, you can no longer use the regular events service plugin. Instead, you now need to import the events service plugin from this package:

import { createEventRecurrencePlugin, createEventsServicePlugin } from "@schedule-x/event-recurrence";
 
const recurrencePlugin = createEventRecurrencePlugin();
const eventsServicePlugin = createEventsServicePlugin();
 
const calendar = createCalendar({
  /* other config */
 
  plugins: [
    recurrencePlugin,
    eventsServicePlugin
  ]
});
 
calendar.render(document.getElementById('calendar'));
 
// Add an event
eventsServicePlugin.add({
  id: 1,
  title: 'New event',
  start: '2024-02-05 14:00',
  end: '2024-02-05 15:00',
  rrule: 'FREQ=WEEKLY;COUNT=3'
});
 
// Update
eventsServicePlugin.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 = eventsServicePlugin.get(123);
 
// Get all
const events = eventsServicePlugin.getAll();
 
// Remove an event with id 123
eventsServicePlugin.remove(123);
Calendar ControlsScroll Controller