Correct and idiomatic ways to use the <mds-pref-mode> component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared preference system documented in agents/theming.md and the shared component rules in agents/conventions.md.

Default Usage Inside mds-pref

The canonical form. Slot <mds-pref-mode> as a direct child of <mds-pref> with no extra props. The component restores the user’s previously persisted mode automatically on load.

<mds-pref>
  <mds-pref-mode></mds-pref-mode>
</mds-pref>

Setting an Initial Mode

Pass mode to force the selector to start on a specific mode rather than reading from localStorage. Useful when the host application controls preference state centrally. The forced mode is also written to localStorage on every load, replacing the user’s last choice.

<mds-pref>
  <mds-pref-mode mode="dark"></mds-pref-mode>
</mds-pref>

Using system Mode for OS-Aware Default

mode="system" resolves to light or dark based on the OS prefers-color-scheme media query. Use this as the explicit starting point when you want the app to follow the OS without the user having to choose.

<mds-pref>
  <mds-pref-mode mode="system"></mds-pref-mode>
</mds-pref>

Choosing a Transition Style

transition controls the visual effect when switching between schemes. Use smooth (default) for a mid-fade overlay that hides the color flip, flash for an instant switch with a brief full-screen pulse, or none for a hard switch with no animation.

<!-- Smooth fade (default) -->
<mds-pref-mode transition="smooth"></mds-pref-mode>

<!-- Instant flash pulse -->
<mds-pref-mode transition="flash"></mds-pref-mode>

<!-- No animation -->
<mds-pref-mode transition="none"></mds-pref-mode>

Listening for Mode Changes

The component emits mdsPrefChange with { preference: 'mode' } each time the mode is applied, on load and on each pick, so expect repeats with the same mode; another instance that mirrors the pick does not emit it. Listen for this event to react in application code - for example to sync a preference state store - and read the current value from the mode prop.

<mds-pref>
  <mds-pref-mode id="mode-selector"></mds-pref-mode>
</mds-pref>

<script>
  document.getElementById('mode-selector').addEventListener('mdsPrefChange', (e) => {
    console.log('Modalita tema cambiata:', e.detail.preference);
  });
</script>

Controlling Size via the Parent

size is forwarded to the internal tab items. <mds-pref> forwards its own size to every mds-pref-* child only when that prop changes after load, not from the initial markup: in markup, set the same size on every preference control to keep the panel at one tab size.

<mds-pref>
  <mds-pref-mode size="sm"></mds-pref-mode>
  <mds-pref-contrast size="sm"></mds-pref-contrast>
</mds-pref>

Customizing the Transition Overlay

Tune the overlay timing and stacking order via the documented --mds-pref-mode-overlay-* CSS custom properties. Set them on the host or a parent selector. Use Magma time tokens where available so animations stay in sync with the design system.

mds-pref-mode {
  --mds-pref-mode-overlay-show-duration: 400ms;
  --mds-pref-mode-overlay-fadeout-duration: 250ms;
  --mds-pref-mode-overlay-z-index: 9000;
}