# Recurrence

> Build recurring events in dash-mui-scheduler with EventCalendarPremium using RRULE strings, RRULE objects and exception dates.

---

.. llms_copy::Recurrence

.. toc::

### Recurrence (Premium)

Recurring events are a **Premium** feature. Use `dms.EventCalendarPremium`
instead of `dms.EventCalendar` — it is identical to the Community calendar but
adds a recurrence engine, a Recurrence tab in the edit dialog, and two new
per-event keys: `rrule` and `exDates`.

.. admonition::Premium
    :color: yellow

    `EventCalendarPremium` requires a MUI X Premium license key. Pass it via
    `licenseKey=os.environ.get("MUI_X_LICENSE_KEY", "")`. Without a valid key
    the calendar still renders and is fully interactive, but a MUI watermark is
    shown over it. That is expected — supply a real key to remove it.

The data boundary is unchanged from the Community calendar. `events` is a list
of plain dicts and is **both input and output**: the component writes the full
array back on every create, move, resize or delete. Dates are ISO **strings**
(for example `"2024-01-15T10:00:00"` for wall time, or a trailing `Z` for UTC),
never Python `datetime` objects. Recurring series are stored as a *single*
event dict carrying an `rrule`; the calendar expands it into occurrences for
display only.

### Recurrence as an RRULE string

The simplest form sets `event["rrule"]` to an RFC-5545 RRULE string. The event
below repeats every week on Monday, Wednesday and Friday:

```text
FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,WE,FR
```

`FREQ` is one of `DAILY`, `WEEKLY`, `MONTHLY`, `YEARLY`. `BYDAY` codes are
`MO TU WE TH FR SA SU` (for monthly rules you may prefix an ordinal, e.g.
`2TU` = second Tuesday, `-1FR` = last Friday). You can also add `COUNT`,
`UNTIL` (an ISO string), `BYMONTHDAY` (1–31) and `BYMONTH` (1–12).

.. exec::docs.recurrence.recurrence_string


```python
# File: docs/recurrence/recurrence_string.py

import os

from dash import Input, Output, callback
import dash_mantine_components as dmc
import dash_mui_scheduler as dms

# Premium events may carry an `rrule`. The RRULE string form follows RFC-5545:
# this event recurs every week on Monday, Wednesday and Friday at 10:00.
events = [
    {
        "id": "standup",
        "title": "Team Standup",
        "start": "2024-01-15T10:00:00",
        "end": "2024-01-15T10:30:00",
        "color": "blue",
        "rrule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,WE,FR",
    },
    {
        "id": "review",
        "title": "Sprint Review",
        "start": "2024-01-19T15:00:00",
        "end": "2024-01-19T16:00:00",
        "color": "purple",
    },
]

component = dmc.Stack(
    [
        dms.EventCalendarPremium(
            id="recurrence-string-cal",
            licenseKey=os.environ.get("MUI_X_LICENSE_KEY", ""),
            events=events,
            defaultView="week",
            defaultVisibleDate="2024-01-15",
            height=600,
        ),
        dmc.Text("Last action:", fw=600, size="sm"),
        dmc.Code(id="recurrence-string-action", block=True),
    ],
    gap="sm",
)


@callback(
    Output("recurrence-string-action", "children"),
    Input("recurrence-string-cal", "lastAction"),
)
def show_action(last_action):
    if not last_action:
        return "No action yet — drag, create, resize or delete an occurrence."
    return f"{last_action.get('type')} @ {last_action.get('event_timestamp')}"
```


### Recurrence as an object + exception dates

Instead of a string, `rrule` may be an object. This is convenient when you are
building the rule programmatically:

```python
{"freq": "WEEKLY", "interval": 1, "byDay": ["MO", "WE", "FR"], "count": 10}
```

The keys mirror the RRULE parts: `freq`, `interval`, `byDay`, `byMonthDay`,
`byMonth`, `count` and `until`. To remove individual occurrences from a series
without breaking the rule, add `exDates` — a list of ISO strings naming the
start times to skip:

```python
"exDates": ["2024-01-17T08:00:00", "2024-01-19T08:00:00"]
```

The example below recurs every weekday for ten occurrences, with two dates
excluded. Note that even though the calendar shows many occurrences, the
`events` output still contains a single definition dict.

.. exec::docs.recurrence.recurrence_object


```python
# File: docs/recurrence/recurrence_object.py

import os

from dash import Input, Output, callback
import dash_mantine_components as dmc
import dash_mui_scheduler as dms

# `rrule` may also be an object instead of a string. Here the event recurs
# every weekday morning for a total of 10 occurrences, but two specific
# dates are removed from the series via `exDates` (ISO strings).
events = [
    {
        "id": "yoga",
        "title": "Morning Yoga",
        "start": "2024-01-15T08:00:00",
        "end": "2024-01-15T08:45:00",
        "color": "green",
        "rrule": {
            "freq": "WEEKLY",
            "interval": 1,
            "byDay": ["MO", "TU", "WE", "TH", "FR"],
            "count": 10,
        },
        "exDates": [
            "2024-01-17T08:00:00",
            "2024-01-19T08:00:00",
        ],
    },
]

component = dmc.Stack(
    [
        dms.EventCalendarPremium(
            id="recurrence-object-cal",
            licenseKey=os.environ.get("MUI_X_LICENSE_KEY", ""),
            events=events,
            defaultView="week",
            defaultVisibleDate="2024-01-15",
            height=600,
        ),
        dmc.Text("Occurrence count in events output:", fw=600, size="sm"),
        dmc.Code(id="recurrence-object-count", block=True),
    ],
    gap="sm",
)


@callback(
    Output("recurrence-object-count", "children"),
    Input("recurrence-object-cal", "events"),
)
def show_count(events_out):
    # The component writes the full event array back on every edit. The
    # recurring definition stays a single dict with `rrule`/`exDates`;
    # the UI expands it into occurrences for display only.
    return f"{len(events_out or [])} stored event definition(s)"
```


### Reading edits back

As with the Community calendar, you do not need a callback for the calendar to
be interactive — drags, creates and deletes round-trip through Dash on their
own. Add a callback only to *display* outputs. The `lastAction` output is
`{type, event, event_timestamp}`, where `type` is one of `create`, `update`,
`delete`, `move`, `resize` or `change`. The first example above wires
`lastAction` into a code block so you can watch edits as they happen.

### EventCalendarPremium props

`EventCalendarPremium` accepts every `EventCalendar` prop plus `licenseKey`,
and its `events` may include `rrule` and `exDates`.

.. kwargs::dash_mui_scheduler.EventCalendarPremium


---

*Source: /recurrence*