Preferences

Control the EventCalendar's default display preferences and the user-facing preferences menu in dash-mui-scheduler.

---

.. llms_copy::Preferences

.. toc::

Preferences

Every calendar exposes a small set of user preferences — am/pm clock, which day the week starts on, whether weekends and week numbers are shown, and so on. These are surfaced through a built-in preferences menu (the gear button in the calendar header) so users can tweak the view themselves.

In dash_mui_scheduler you control three related things:

• defaultPreferences — the initial, uncontrolled preference values applied on load.
• preferences — the controlled IN+OUT version. It seeds the UI *and* reports the

current values back to Dash whenever the user changes a setting.

• preferencesMenuConfig — which entries appear in the preferences menu (or whether the

menu shows at all).

All of these work the same way on EventCalendar, EventCalendarPremium, and (a smaller subset) on EventTimeline.

Default preferences

defaultPreferences is a dict. Set only the keys you care about — anything omitted falls back to the component's own defaults.

| Key | Type | Meaning | | --- | --- | --- | | ampm | bool | 12-hour (True) vs 24-hour (False) clock | | weekStartsOn | int 0–6 | First day of the week (0 = Sunday … 1 = Monday) | | showWeekends | bool | Show Saturday/Sunday columns | | showWeekNumber | bool | Show the ISO week number | | isSidePanelOpen | bool | Whether the date/resource side panel starts open | | showEmptyDaysInAgenda | bool | Keep empty days visible in the agenda view |

.. admonition::Uncontrolled vs controlled :color: blue

Use defaultPreferences when you just want a starting configuration and don't need to read changes back. Use preferences when you want the current values in a callback — it is both an input and an output, so the component writes the full preferences dict back on every toggle.

Reading preferences

Because preferences is IN+OUT, you can attach a callback whose only job is to read the current values. The example below seeds the calendar with a Monday week start, 24-hour clock, and visible week numbers via defaultPreferences, then echoes the live preferences dict each time the user changes something in the menu.

.. exec::docs.preferences.preferences_default

```python

File: docs/preferences/preferences_default.py

import json

import dash_mantine_components as dmc from dash import Input, Output, State, callback, html

import dash_mui_scheduler as dms

events = [ {"id": "1", "title": "Design review", "start": "2024-01-15T09:00:00", "end": "2024-01-15T10:30:00", "color": "blue"}, {"id": "2", "title": "Saturday standup", "start": "2024-01-20T11:00:00", "end": "2024-01-20T12:00:00", "color": "green"}, ]

preferences is controlled IN + OUT. We seed it, drive it from the switches

below, and read it back in a callback. (The calendar also writes it back when

the user toggles a setting in its own gear menu.)

INITIAL = { "ampm": False, "weekStartsOn": 1, "showWeekends": True, "showWeekNumber": True, "isSidePanelOpen": True, "showEmptyDaysInAgenda": True, }

component = html.Div( [ dmc.Group( [ dmc.Switch(id="pref-ampm", label="12-hour clock", checked=INITIAL["ampm"]), dmc.Switch(id="pref-weekends", label="Show weekends", checked=INITIAL["showWeekends"]), dmc.Switch(id="pref-weeknum", label="Week numbers", checked=INITIAL["showWeekNumber"]), ], mb="md", ), dms.EventCalendar( id="preferences-default-cal", height=560, events=events, defaultView="week", defaultVisibleDate="2024-01-15", preferences=INITIAL, ), dmc.Code(id="preferences-default-readout", block=True, mt="sm"), ] )

@callback( Output("preferences-default-cal", "preferences"), Input("pref-ampm", "checked"), Input("pref-weekends", "checked"), Input("pref-weeknum", "checked"), State("preferences-default-cal", "preferences"), prevent_initial_call=True, ) def set_preferences(ampm, weekends, week_number, current): prefs = dict(current or INITIAL) prefs.update({"ampm": ampm, "showWeekends": weekends, "showWeekNumber": week_number}) return prefs

@callback( Output("preferences-default-readout", "children"), Input("preferences-default-cal", "preferences"), ) def show_preferences(preferences): # preferences flows back out whenever it changes — from the switches above # or from the calendar's own gear menu. return json.dumps(preferences or INITIAL, indent=2, sort_keys=True) ```

The readout updates as you toggle items in the calendar's preferences menu — no extra plumbing required, since the component pushes the new dict back through Dash's normal setProps round-trip.

The preferences menu

preferencesMenuConfig controls the menu itself:

• Pass False to hide the entire preferences menu (useful for a locked-down, read-only

display).

• Pass a dict to show or hide individual entries. Each key is a boolean:

toggleWeekendVisibility, toggleWeekNumberVisibility, toggleAmpm, toggleEmptyDaysInAgenda, and toggleWeekStartsOn.

The first calendar below keeps the weekend, week-number, and am/pm toggles but removes the "empty days in agenda" and "week starts on" entries. The second passes preferencesMenuConfig=False, so its menu button disappears entirely.

.. exec::docs.preferences.preferences_menu

```python

File: docs/preferences/preferences_menu.py

import dash_mantine_components as dmc from dash import html

import dash_mui_scheduler as dms

events = [ {"id": "1", "title": "Sprint planning", "start": "2024-01-15T13:00:00", "end": "2024-01-15T14:00:00", "color": "indigo"}, {"id": "2", "title": "Retro", "start": "2024-01-18T15:00:00", "end": "2024-01-18T16:00:00", "color": "amber"}, ]

preferencesMenuConfig prunes the gear/preferences menu.

Pass a dict to toggle individual items, or False to hide the whole menu.

component = dmc.Stack( [ dmc.Text("Custom menu — only weekends, week number, and AM/PM toggles", fw=600, size="sm"), dms.EventCalendar( id="preferences-menu-cal", height=480, events=events, defaultView="week", defaultVisibleDate="2024-01-15", preferencesMenuConfig={ "toggleWeekendVisibility": True, "toggleWeekNumberVisibility": True, "toggleAmpm": True, "toggleEmptyDaysInAgenda": False, "toggleWeekStartsOn": False, }, ), dmc.Text("Menu hidden — preferencesMenuConfig=False (no gear button)", fw=600, size="sm", mt="md"), dms.EventCalendar( id="preferences-menu-hidden-cal", height=480, events=events, defaultView="week", defaultVisibleDate="2024-01-15", preferencesMenuConfig=False, ), ], gap="xs", ) ```

.. admonition::Menu config vs values :color: green

preferencesMenuConfig only decides which controls are *available* to the user. It does not change the actual preference values — set those with defaultPreferences / preferences. Hiding a toggle simply means the user can't change that setting from the UI; you can still set it programmatically.

Component reference

.. kwargs::dash_mui_scheduler.EventCalendar

---

*Source: /preferences*