Localization & Timezones

Set the display timezone, 12h/24h clock, week start day, and translate UI labels in the dash-mui-scheduler calendar.

Localization & Timezones

The scheduler can render the same events for users in different timezones and locales without ever touching the event data itself. Four knobs cover almost everything:

• displayTimezone — which timezone the grid is drawn in (render-only).
• preferences.ampm — 12-hour vs 24-hour clock.
• preferences.weekStartsOn — which weekday a week begins on.
• localeText — overrides for individual UI label strings.

The most important idea on this page is the data boundary: an event's start / end are ISO strings that you own. Localization changes how those times are displayed, not what they are.

Display timezone

displayTimezone controls the timezone the calendar grid renders in. It accepts an IANA timezone name like "America/New_York" or "Asia/Tokyo", or one of the special values:

Changing displayTimezone only changes where event blocks are drawn on the grid. It does not rewrite your events. The ISO strings you pass in stay exactly as they are, and the array the component writes back keeps the same wall-clock / UTC strings. Think of it as a viewport over fixed instants.

How the strings are interpreted matters here:

• "2024-01-17T18:00:00Z" — the trailing Z means UTC. It refers to one fixed

instant, so it lands at different wall-clock positions in New York vs Tokyo.

• "2024-01-15T09:00:00" — no Z is a wall-clock time with no zone attached.

The example below renders one shared list of events in two calendars — the only difference is displayTimezone. Note how the "Release window (UTC)" event (which uses a Z suffix) shifts between the two grids, while the rest stay put.

# File: docs/localization/timezones.py

from dash import html
import dash_mantine_components as dmc

import dash_mui_scheduler as dms

# One shared set of events. Each `start`/`end` is an ISO string.
# These carry no trailing "Z", so they are wall-clock times — the same
# instant the component then re-renders in whatever displayTimezone is set.
events = [
    {
        "id": "1",
        "title": "Morning sync",
        "start": "2024-01-15T09:00:00",
        "end": "2024-01-15T10:00: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": "Release window (UTC)",
        "start": "2024-01-17T18:00:00Z",
        "end": "2024-01-17T19:00:00Z",
        "color": "green",
    },
]

# Two calendars, identical events, different `displayTimezone`.
# displayTimezone is render-only: it shifts where blocks appear on the grid,
# but the underlying event data (the ISO strings above) never changes.
component = dmc.Stack(
    [
        dmc.Text("New York (America/New_York)", fw=600, size="sm"),
        dms.EventCalendar(
            id="localization-tz-ny-cal",
            events=events,
            defaultView="week",
            defaultVisibleDate="2024-01-15",
            displayTimezone="America/New_York",
            height=560,
        ),
        dmc.Text("Tokyo (Asia/Tokyo)", fw=600, size="sm"),
        dms.EventCalendar(
            id="localization-tz-tokyo-cal",
            events=events,
            defaultView="week",
            defaultVisibleDate="2024-01-15",
            displayTimezone="Asia/Tokyo",
            height=560,
        ),
    ],
    gap="sm",
)

12-hour vs 24-hour clock

The clock format lives in preferences.ampm:

• ampm=True → 12-hour clock (2:00 PM).
• ampm=False → 24-hour clock (14:00).

Set it via defaultPreferences (uncontrolled, initial value) or preferences (controlled IN+OUT, also readable in a callback). Users can flip it themselves from the preferences menu unless you disable that toggle. See the Preferences page for the full preferences dict and menu config.

Week start

preferences.weekStartsOn is an integer from 0 to 6 that picks the first day of the week:

The example below seeds a Monday-first, 24-hour calendar with week numbers via defaultPreferences. Because these are preferences, they apply to the week, month, and agenda layouts consistently.

# File: docs/localization/week_start.py

from dash import html

import dash_mui_scheduler as dms

events = [
    {
        "id": "1",
        "title": "Sprint planning",
        "start": "2024-01-15T09:00:00",
        "end": "2024-01-15T10:30:00",
        "color": "indigo",
    },
    {
        "id": "2",
        "title": "Saturday demo",
        "start": "2024-01-20T11:00:00",
        "end": "2024-01-20T12:00:00",
        "color": "amber",
    },
    {
        "id": "3",
        "title": "Sunday on-call",
        "start": "2024-01-21T08:00:00",
        "end": "2024-01-21T09:00:00",
        "color": "red",
    },
]

# weekStartsOn (0 = Sunday … 6 = Saturday) and ampm live inside preferences.
# Here defaultPreferences seeds a Monday-first, 24-hour calendar on load.
component = html.Div(
    dms.EventCalendar(
        id="localization-week-start-cal",
        events=events,
        defaultView="week",
        defaultVisibleDate="2024-01-15",
        defaultPreferences={
            "weekStartsOn": 1,
            "ampm": False,
            "showWeekends": True,
            "showWeekNumber": True,
        },
        height=560,
    )
)

Both ampm and weekStartsOn are keys inside the preferences dict — there are no top-level ampm / weekStartsOn props. Pass them through defaultPreferences={...} or the controlled preferences={...}.

Label overrides

localeText is a dict of overrides for the calendar's built-in UI label strings — button captions, menu items, placeholders, and so on. Pass it as a dict where each value replaces the default text for that key:

dms.EventCalendar(
    id="my-cal",
    events=events,
    localeText={
        "today": "Aujourd'hui",
        "week": "Semaine",
        "month": "Mois",
    },
)

The MUI X Scheduler's locale text includes both plain strings and functions (for example, labels that format a date range). Because props cross the Dash boundary as JSON, only the string-valued keys can be overridden from Python — function-valued entries can't be passed and will fall back to their defaults. Use localeText for static caption text, not for dynamic formatters.

For full locale coverage (including the function-valued formatters), you would provide a translation at the React/JS layer. From Dash, localeText is best treated as a way to retitle the static buttons and menu items.

Timezones and the data you store

Because displayTimezone never edits your events, your storage stays predictable:

• Store events as ISO strings. Add a Z (or an explicit offset) when a value

is a fixed UTC instant; omit it when it's a floating wall-clock time.

• An event may also carry its own timezone (IANA) key in its dict to anchor it

to a specific zone independent of the display timezone.

• When the component writes events back after a drag/create/resize, it returns

ISO strings in the same shape — so a round-trip through Dash doesn't silently re-localize your data.

The MUI X Scheduler is in beta. Timezone and locale behavior can change between releases; verify edge cases (DST boundaries, cross-zone all-day events) against your target version.

Component reference

EventCalendar props

Source: /localization