RRule Plugin

The RRule plugin is a connector to the rrule js library. It is powerful for specifying recurring events, moreso than FullCalendar’s built-in simple event recurrence.

Usage with NPM#

First, install the @fullcalendar/rrule package:

npm install --save @fullcalendar/rrule

Then, create a new calendar and pass in the plugins:

import { Calendar } from "fullcalendar";
import dayGridPlugin from "fullcalendar/daygrid";
import rrulePlugin from "@fullcalendar/rrule";

const calendarEl = document.getElementById("calendar");
const calendar = new Calendar(calendarEl, {
  plugins: [rrulePlugin, dayGridPlugin],
  events: [
    // event data. see below
  ],
});

calendar.render();

Usage with Script Tags#

The plugin is not part of FullCalendar’s all/global.js bundle. If you are using script tags, add the rrule library and the plugin’s own global.js:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <!-- RRULE LIB -->
+   <script src="https://cdn.jsdelivr.net/npm/rrule@2.8.1/dist/es5/rrule.min.js"></script>

    <!-- STANDARD JS -->
    <script src="https://cdn.jsdelivr.net/npm/fullcalendar@7.1.1/all/global.js"></script>

    <!-- RRULE PLUGIN. must go AFTER the rrule lib and the standard JS -->
+   <script src="https://cdn.jsdelivr.net/npm/@fullcalendar/rrule@7.1.1/global.js"></script>

    <!-- THEME JS -->
    <script src="https://cdn.jsdelivr.net/npm/fullcalendar@7.1.1/themes/monarch/global.js"></script>

    <!-- STYLESHEETS -->
    <link href='https://cdn.jsdelivr.net/npm/fullcalendar@7.1.1/skeleton.css' rel='stylesheet' />
    <link href='https://cdn.jsdelivr.net/npm/fullcalendar@7.1.1/themes/monarch/theme.css' rel='stylesheet' />
    <link href='https://cdn.jsdelivr.net/npm/fullcalendar@7.1.1/themes/monarch/palettes/purple.css' rel='stylesheet' />

    <script>
      document.addEventListener("DOMContentLoaded", function () {
        const calendarEl = document.getElementById("calendar");
        const calendar = new FullCalendar.Calendar(calendarEl, {
+         events: [
+           // event data. see below
+         ]
        });
        calendar.render();
      });
    </script>
  </head>
  <body>
    <div id="calendar"></div>
  </body>
</html>

The rrule script defines the rrule browser global, which the plugin reads. The plugin’s global.js registers itself, so there is no plugins array to write. It works the same way alongside the Web Component’s all/global.js.

View a live demo

Event Data#

When using the RRule plugin, event parsing accepts these new properties:

rrule	Accepts whatever the rrule lib accepts for a new RRule. See the RRule docs. You can specify a string or an object.
exdate	A date input or array of date inputs.
exrule	An object or array of objects. The object is whatever the new RRule constructor takes. See the RRule docs.
duration	Must be something that parses into a Duration. If not specified, each event will appear to have the default duration. See defaultAllDayEventDuration, defaultTimedEventDuration, and forceEventDuration for more info.

The rrule property#

You can specify the rrule property as an object:

const calendar = new FullCalendar.Calendar(calendarEl, {
  events: [
    {
      title: "my recurring event",
      rrule: {
        freq: "weekly",
        interval: 5,
        byweekday: ["mo", "fr"],
        dtstart: "2012-02-01T10:30:00", // will also accept '20120201T103000'
        until: "2012-06-01", // will also accept '20120201'
      },
    },
  ],
});

If you’re specifying an object, you can write some of the properties in a way that’s more convenient than what rrule requires. You don’t need to use the RRule constants like RRule.WEEKLY. You can just specify the string 'weekly'. This is better for JSON serialization.

You can also specify rrule as a string:

const calendar = new FullCalendar.Calendar(calendarEl, {
  events: [
    {
      title: "my recurring event",
      rrule:
        "DTSTART:20120201T103000Z\nRRULE:FREQ=WEEKLY;INTERVAL=5;UNTIL=20120601;BYDAY=MO,FR",
    },
  ],
});

Exclusion Properties#

As of version 5.5.0, you can supply properties that exclude certain dates generated by the previously supplied rrule. These only work if you’re defining rrule as an object. If you’re defining rrule as as string, you should write the exclusions within the string itself.

You can exclude one or more explicit dates using exdate:

const calendar = new FullCalendar.Calendar(calendarEl, {
  events: [
    {
      title: "my recurring event",
      rrule: {
        freq: "weekly",
        dtstart: "2012-02-01",
      },
      exdate: ["2012-02-08"], // will also accept a single string
    },
  ],
});

Or, you can use a separate rrule to define the dates you want excluded, using exrule:

const calendar = new FullCalendar.Calendar(calendarEl, {
  events: [
    {
      title: "my recurring event",
      rrule: {
        freq: "weekly",
        dtstart: "2012-02-01",
      },
      exrule: {
        // will also accept an array of these objects
        freq: "weekly",
        dtstart: "2012-02-15",
        until: "2012-02-22",
      },
    },
  ],
});

Times and Time Zones#

The dtstart and until dates (or DTSTART and UNTIL when specifying a string) will be parsed in this way:

• If a time part is not specified (like T10:30:00 or T103000), the event is assumed to be all-day.
• If a time zone part is not specified (like Z), the event will assume the timeZone of the calendar.