Event Timeline

Build a resource-row, Gantt-style timeline in dash-mui-scheduler with EventTimeline — resources as rows, multi-day allocation bars and zoom presets.

Event Timeline (Premium)

dms.EventTimeline is a resource-row, Gantt-style timeline. Where the calendar lays events out on a day/week/month grid, the timeline turns each resource into a row and draws every event as a horizontal allocation bar on its row, across a configurable zoom preset. It wraps the MUI X EventTimelinePremium and, like every component here, is currently beta.

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

The data boundary is the same as the 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-15T09:00:00" for wall time, or a trailing Z for UTC), never Python datetime objects. The read-only lastAction output is {type, event, event_timestamp}, where type is one of create, update, delete, move, resize or change.

Resources as rows

A timeline needs resources — they are the rows. Each resource is a dict with at least an id and title, plus an optional eventColor:

resources = [
    {"id": "team-a", "title": "Team A", "eventColor": "blue"},
    {"id": "team-b", "title": "Team B", "eventColor": "green"},
]

Each event names its row through the resource key, which must match one of the resource ids. On the timeline events should almost always have a resource — shouldEventRequireResource defaults to True here. The column that lists the row labels is titled with resourceColumnLabel (for example "Team"). The example below places several multi-day allocation bars across three rows and opens at the dayAndWeek zoom level.

# File: docs/event_timeline/timeline_basic.py

import os

from dash import html
import dash_mui_scheduler as dms

# On a timeline, resources are the ROWS. Each event sits on the row whose id
# matches its `resource` key. Resources carry their own eventColor.
resources = [
    {"id": "team-a", "title": "Team A", "eventColor": "blue"},
    {"id": "team-b", "title": "Team B", "eventColor": "green"},
    {"id": "team-c", "title": "Team C", "eventColor": "orange"},
]

# Allocation bars span days. Dates are ISO strings (never Python datetime),
# and `events` is both input and output — the component writes the full array
# back on every create, move, resize or delete.
events = [
    {
        "id": "alloc-1",
        "title": "Discovery",
        "start": "2024-01-15T09:00:00",
        "end": "2024-01-17T17:00:00",
        "resource": "team-a",
    },
    {
        "id": "alloc-2",
        "title": "Build phase",
        "start": "2024-01-18T09:00:00",
        "end": "2024-01-23T17:00:00",
        "resource": "team-a",
    },
    {
        "id": "alloc-3",
        "title": "API integration",
        "start": "2024-01-16T09:00:00",
        "end": "2024-01-20T17:00:00",
        "resource": "team-b",
    },
    {
        "id": "alloc-4",
        "title": "QA & hardening",
        "start": "2024-01-22T09:00:00",
        "end": "2024-01-25T17:00:00",
        "resource": "team-b",
    },
    {
        "id": "alloc-5",
        "title": "Launch prep",
        "start": "2024-01-19T09:00:00",
        "end": "2024-01-24T17:00:00",
        "resource": "team-c",
    },
]

component = html.Div(
    dms.EventTimeline(
        id="event_timeline-basic",
        licenseKey=os.environ.get("MUI_X_LICENSE_KEY", ""),
        events=events,
        resources=resources,
        resourceColumnLabel="Team",
        defaultPreset="dayAndWeek",
        defaultVisibleDate="2024-01-15",
        height=400,
    )
)

Zoom presets

A preset controls how much time one screen of the timeline spans and how the header is divided. There are five: dayAndHour (the default), dayAndMonth, dayAndWeek, monthAndYear and year. Two props drive this:

• defaultPreset / preset — the active zoom level. defaultPreset is

uncontrolled (set it once at load); preset is controlled in + out, so a callback can both set it and read the user's changes back.

• presets — the list of presets offered in the timeline's own zoom switcher.

To drive the zoom from your own UI, wire a dmc.SegmentedControl to the preset prop. Because preset is controlled in + out, the callback below sets the zoom whenever the segmented control changes:

@callback(
    Output("event_timeline-presets", "preset"),
    Input("event_timeline-presets-control", "value"),
)
def set_preset(value):
    return value

# File: docs/event_timeline/timeline_presets.py

import os

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

# Rows.
resources = [
    {"id": "mixer", "title": "Mixer", "eventColor": "purple"},
    {"id": "studio", "title": "Studio", "eventColor": "teal"},
]

# A few multi-day allocations so the effect of each zoom preset is visible.
events = [
    {
        "id": "preset-1",
        "title": "Album mixdown",
        "start": "2024-01-15T10:00:00",
        "end": "2024-01-19T18:00:00",
        "resource": "mixer",
    },
    {
        "id": "preset-2",
        "title": "Tracking sessions",
        "start": "2024-01-16T09:00:00",
        "end": "2024-01-22T20:00:00",
        "resource": "studio",
    },
    {
        "id": "preset-3",
        "title": "Mastering",
        "start": "2024-01-23T10:00:00",
        "end": "2024-01-25T16:00:00",
        "resource": "mixer",
    },
]

# `preset` is controlled in + out: the SegmentedControl drives the zoom level.
# The five presets are dayAndHour, dayAndMonth, dayAndWeek, monthAndYear, year.
presets = ["dayAndHour", "dayAndWeek", "dayAndMonth", "monthAndYear", "year"]

component = dmc.Stack(
    [
        dmc.SegmentedControl(
            id="event_timeline-presets-control",
            data=[
                {"label": "Day / Hour", "value": "dayAndHour"},
                {"label": "Day / Week", "value": "dayAndWeek"},
                {"label": "Day / Month", "value": "dayAndMonth"},
                {"label": "Month / Year", "value": "monthAndYear"},
                {"label": "Year", "value": "year"},
            ],
            value="dayAndWeek",
        ),
        dms.EventTimeline(
            id="event_timeline-presets",
            licenseKey=os.environ.get("MUI_X_LICENSE_KEY", ""),
            events=events,
            resources=resources,
            resourceColumnLabel="Resource",
            presets=presets,
            preset="dayAndWeek",
            defaultVisibleDate="2024-01-15",
            height=400,
        ),
    ],
    gap="sm",
)


@callback(
    Output("event_timeline-presets", "preset"),
    Input("event_timeline-presets-control", "value"),
)
def set_preset(value):
    return value

EventTimeline props

EventTimeline shares most of its props with the calendar (events, resources, visibility, drag/resize flags, preferences, timezone) and adds the timeline specifics: resourceColumnLabel, preset / defaultPreset and presets. It needs a licenseKey.

EventTimeline props

Source: /event-timeline