Quickstart

Install dash-mui-scheduler and render your first MUI X Scheduler calendar and timeline in Dash.

Walkthrough

A quick video tour of dash-mui-scheduler — the calendar, the resource timeline, and the radial charts in action.

<!-- component rendered from docs/quickstart/video.py; source withheld by :code: false -->

Installation

dash-mui-scheduler wraps the MUI X Scheduler for Dash. Install it from PyPI:

pip install dash-mui-scheduler

The MUI X Scheduler is in beta, and so are these wrappers. Props and behaviour may change between releases. Pin your version if you need stability.

There are three components:

• dms.EventCalendar — Community (MIT). Day / week / month / agenda calendar. No license key.
• dms.EventCalendarPremium — adds recurrence (rrule / exDates). Needs a licenseKey.
• dms.EventTimeline — Premium resource-row timeline. Needs a licenseKey.

This page covers the two you will reach for first: EventCalendar and EventTimeline.

Rendering an Event Calendar

Import the package as dms, hand it a list of events, and point it at a date. A standalone calendar is already fully interactive — drag, resize, create, and delete all work and persist through Dash's own setProps round-trip, with no callback required.

The dcc.Markdown readout below is wired to the calendar's lastAction output so you can watch each edit as it happens (see Reading changes).

# File: docs/quickstart/render_calendar.py

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

# events are plain dicts; dates are ISO strings (no Z = wall time).
# Required keys: id, title, start, end. Everything else is optional.
events = [
    {
        "id": "1",
        "title": "Team Standup",
        "start": "2024-01-15T09:00:00",
        "end": "2024-01-15T09:30:00",
        "color": "blue",
    },
    {
        "id": "2",
        "title": "Design Review",
        "start": "2024-01-16T13:00:00",
        "end": "2024-01-16T14:30:00",
        "color": "purple",
    },
    {
        "id": "3",
        "title": "Sprint Demo",
        "start": "2024-01-18T15:00:00",
        "end": "2024-01-18T16:00:00",
        "color": "green",
    },
]

component = dmc.Stack(
    [
        dms.EventCalendar(
            id="quickstart-cal",
            events=events,
            defaultVisibleDate="2024-01-15",
            defaultView="week",
            height=600,
        ),
        dmc.Text("Last action", fw=600, size="sm"),
        dcc.Markdown(id="quickstart-cal-readout"),
    ],
    gap="sm",
)


@callback(
    Output("quickstart-cal-readout", "children"),
    Input("quickstart-cal", "lastAction"),
)
def show_last_action(last_action):
    if not last_action:
        return "_Drag, create, or delete an event to see the last action._"
    action_type = last_action.get("type")
    event = last_action.get("event") or {}
    title = event.get("title", "—")
    return f"**{action_type}** → `{title}`"

The events model

events is a list of plain dicts. Dates are ISO strings, never Python datetime objects. A string with no trailing Z (e.g. "2024-01-15T10:00:00") is wall time; a trailing Z (e.g. "2024-01-15T10:00:00Z") is UTC.

Every event requires four keys:

Common optional keys include color (one of the 11 palette names: red, pink, purple, indigo, blue, teal, green, lime, amber, orange, grey), description, allDay, resource, draggable, resizable, and readOnly.

The component writes the entire new array back to events on every create, move, resize, or delete. Read events in a callback to get the current state, or read lastAction to get just the change that triggered it.

Reading changes

You never need a callback to make the calendar work — only to display what changed. lastAction is an output-only prop shaped like {type, event, event_timestamp}, where type is one of create, update, delete, move, resize, or change, and event is the affected event dict (or None for some actions).

The example above attaches this minimal callback to surface it:

@callback(
    Output("quickstart-cal-readout", "children"),
    Input("quickstart-cal", "lastAction"),
)
def show_last_action(last_action):
    if not last_action:
        return "_Drag, create, or delete an event to see the last action._"
    action_type = last_action.get("type")
    event = last_action.get("event") or {}
    return f"**{action_type}** → `{event.get('title', '—')}`"

Create or drag an event in the calendar above and the readout updates in place.

Rendering an Event Timeline

EventTimeline is the Premium resource-row view — a Gantt-style layout where each resource is a row and each event sits on the row named by its resource id. Resources are dicts like {"id": "team-a", "title": "Team A"}. The timeline shares the same events model (ISO strings, events in/out, lastAction); it just adds zoom presets such as dayAndHour (default), dayAndWeek, and monthAndYear.

EventTimeline (and EventCalendarPremium) are Premium components. Without a valid licenseKey they render with a watermark — that is expected. Set MUI_X_LICENSE_KEY in your environment to remove it. The component still functions either way.

# File: docs/quickstart/render_timeline.py

import os

import dash_mantine_components as dmc
import dash_mui_scheduler as dms

# Resources are the rows of the timeline. Each event points at a resource id.
resources = [
    {"id": "team-a", "title": "Team A"},
    {"id": "team-b", "title": "Team B"},
]

events = [
    {
        "id": "1",
        "title": "Migration",
        "start": "2024-01-15T09:00:00",
        "end": "2024-01-15T15:00:00",
        "resource": "team-a",
        "color": "indigo",
    },
    {
        "id": "2",
        "title": "QA Pass",
        "start": "2024-01-15T11:00:00",
        "end": "2024-01-15T18:00:00",
        "resource": "team-b",
        "color": "amber",
    },
]

component = dmc.Stack(
    [
        dms.EventTimeline(
            id="quickstart-timeline",
            licenseKey=os.environ.get("MUI_X_LICENSE_KEY", ""),
            resources=resources,
            events=events,
            resourceColumnLabel="Teams",
            defaultVisibleDate="2024-01-15",
            defaultPreset="dayAndHour",
            height=400,
        ),
    ],
    gap="sm",
)

EventCalendar props

The full, auto-generated prop reference for the Community EventCalendar:

EventCalendar props

Source: /quickstart