Localization & Timezones

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

---

.. llms_copy::Localization & Timezones

.. toc::

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:

| Value | Meaning | | --- | --- | | "default" | The component's default behavior (the initial value) | | "UTC" | Render everything in UTC | | "locale" | Use the browser's local timezone | | IANA name | Render in that specific zone, e.g. "Europe/Paris" |

.. admonition::displayTimezone is render-only :color: yellow

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.

.. exec::docs.localization.timezones

```python

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](/preferences) 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:

| Value | Day | | --- | --- | | 0 | Sunday | | 1 | Monday | | 2 | Tuesday | | 3 | Wednesday | | 4 | Thursday | | 5 | Friday | | 6 | Saturday |

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.

.. exec::docs.localization.week_start

```python

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, ) ) ```

.. admonition::Where ampm and weekStartsOn live :color: blue

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:

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

.. admonition::Only string-valued labels are settable from Python :color: yellow

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.

.. admonition::Beta :color: blue

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

.. kwargs::dash_mui_scheduler.EventCalendar

---

*Source: /localization*