Event Calendar

The EventCalendar component — a day/week/month/agenda calendar whose events round-trip across the Dash boundary as plain dicts with ISO-string dates.

Overview

dms.EventCalendar wraps the MUI X Event Calendar (Community, MIT — no license key required). It renders a day / week / month / agenda calendar that your users can read and edit: create, drag-to-reschedule, resize and delete events directly in the UI.

import dash_mui_scheduler as dms

The calendar is interactive on its own. A standalone dms.EventCalendar with no callback already persists every create / move / resize / delete, because each edit round-trips through Dash's own setProps. You only add a callback when you want to observe the result — to render the current events, react to the last action, or sync view / visibleDate elsewhere.

The MUI X Scheduler is in beta. APIs may shift between releases. The props documented here are the ones the Dash wrapper exposes today.

The data boundary

Everything the calendar shows and everything the user changes crosses the Dash boundary as plain, JSON-serializable values — no Python datetime objects, no functions. Dates are ISO strings.

Events in, events out

events is a list of dicts and is both an input and an output. You pass events in; the calendar writes the full new array back to the same prop on every create, move, resize and delete. Read it from a callback to keep your own state in sync.

Each event dict has four required keys:

Common optional keys: description, resource (a resource id), allDay, color (one of the 11 palette names), timezone (IANA name), draggable, resizable (bool | 'start' | 'end'), readOnly and className. On EventCalendarPremium, events may also carry rrule and exDates for recurrence.

Always pass dates as strings. "2024-01-15T10:00:00" (no Z) is wall time; "2024-01-15T10:00:00Z" is a UTC instant. displayTimezone controls only how events are rendered — it never rewrites their data.

lastAction (output only)

lastAction is a convenience output describing the most recent change to events. It is a dict:

{"type": "move", "event": { ... }, "event_timestamp": 1705312800000}

type tells you what just happened:

event_timestamp is an epoch-milliseconds integer — use it as a callback trigger that changes on every action, even when the same event is touched twice in a row.

Visible date and other controlled props

visibleDate is an ISO date string (e.g. "2024-01-15") and is controlled both in and out — it is written back when the user navigates. Its uncontrolled twin is defaultVisibleDate. Several props follow the same controlled / uncontrolled pattern: view / defaultView, preferences / defaultPreferences, and visibleResources / defaultVisibleResources.

The calendar follows the surrounding Mantine color scheme. Do not write a theme callback — toggle your app's color scheme and the calendar follows.

A controlled calendar

The example below keeps the calendar uncontrolled (it manages its own edits) and adds a single callback that mirrors the two output sides of the boundary: the live events array and the latest lastAction, both rendered as JSON.

Create, drag, resize or delete an event in the calendar and watch both panels update. The events pinned around 2024-01-15 are visible on load because the calendar starts at defaultVisibleDate="2024-01-15".

# File: docs/event_calendar/overview.py

"""A controlled EventCalendar: the calendar is fully interactive on its own,
and a callback mirrors the live `events` array and the most recent
`lastAction` back to the page as JSON."""

import json

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

# Events cross the Dash boundary as plain dicts with ISO-string dates.
# "...:00" with no "Z" is wall time; a trailing "Z" would mean a UTC instant.
events = [
    {
        "id": "kickoff",
        "title": "Project kickoff",
        "start": "2024-01-15T09:00:00",
        "end": "2024-01-15T10:30:00",
        "color": "blue",
        "description": "Align on scope for the quarter.",
    },
    {
        "id": "design-review",
        "title": "Design review",
        "start": "2024-01-16T13:00:00",
        "end": "2024-01-16T14:00:00",
        "color": "purple",
    },
    {
        "id": "team-lunch",
        "title": "Team lunch",
        "start": "2024-01-17T12:00:00",
        "end": "2024-01-17T13:00:00",
        "color": "green",
    },
    {
        "id": "retro",
        "title": "Sprint retro",
        "start": "2024-01-18T16:00:00",
        "end": "2024-01-18T17:00:00",
        "color": "amber",
    },
]

component = dmc.Stack(
    [
        dms.EventCalendar(
            id="event_calendar-overview-cal",
            events=events,
            defaultView="week",
            defaultVisibleDate="2024-01-15",
            eventColor="teal",
            height=600,
        ),
        dmc.Group(
            [
                dmc.Stack(
                    [
                        dmc.Text("Live events array", fw=600, size="sm"),
                        dmc.Code(
                            id="event_calendar-overview-events",
                            block=True,
                            style={"maxHeight": 320, "overflow": "auto"},
                        ),
                    ],
                    gap=4,
                    style={"flex": 1, "minWidth": 280},
                ),
                dmc.Stack(
                    [
                        dmc.Text("Most recent lastAction", fw=600, size="sm"),
                        dmc.Code(
                            id="event_calendar-overview-action",
                            block=True,
                            style={"maxHeight": 320, "overflow": "auto"},
                        ),
                    ],
                    gap=4,
                    style={"flex": 1, "minWidth": 280},
                ),
            ],
            grow=True,
            align="flex-start",
        ),
    ],
    gap="md",
)


@callback(
    Output("event_calendar-overview-events", "children"),
    Output("event_calendar-overview-action", "children"),
    Input("event_calendar-overview-cal", "events"),
    Input("event_calendar-overview-cal", "lastAction"),
)
def show_boundary(current_events, last_action):
    """Render the two OUTPUT sides of the boundary as pretty JSON."""
    events_json = json.dumps(current_events or [], indent=2)
    action_json = json.dumps(last_action or {}, indent=2)
    return events_json, action_json

Props

Full prop reference for dms.EventCalendar. Use only these props — do not invent new ones.

EventCalendar props

Source: /event-calendar