Pref mode<mds-pref-mode>Generated from @maggioli-design-system/magma@2.3.0dist/documentation.json. Encapsulation: shadow.
The first example of the Pattern page, live. Change its props below and the preview follows; Reset brings the example back as it was.
Props
lockedSchemeenumLocks the mode items forbidden by a scheme-constrained theme, without touching the stored preference: light disables the explicit dark item, dark disables the explicit light item, all (or unset) locks nothing; the system item is never locked. Set by the mds-pref controller from the active theme's scheme; not meant to be set directly.
modeenumSpecifies the preference mode
sizeenumSets the size of the component items nested inside it
transitionenumSpecifies the transition of switching from a mode to another one
Overview
The <mds-pref-mode> web component is the mode preference control of the Magma Design System, usually a direct child of the <mds-pref> panel. It renders a labelled three-way tab (light / system / dark) that lets the user pick a color-scheme mode and applies it globally to the document.
Semantic Behavior
Usually inside <mds-pref>: Placed as a direct slot child of <mds-pref>, alongside the other mds-pref-* controls; it also works on its own, since it applies and stores the mode by itself. What it gives up on its own is in the antipattern docs.Selection follows mode: The active tab reflects whichever mode is currently applied, driven by the mode prop.Global mode application: Selecting a mode applies it document-wide and persists the choice.Persistence on load: The applied mode resolves from mode -> the stored value -> the system default, so a previously chosen mode is restored without an explicit prop.mdsPrefChange event: Emits mdsPrefChange with { preference: 'mode' } every time the mode is applied: on load and on each pick, so one pick can emit it more than once. It bubbles up to <mds-pref>; a mode change needs no reload, so it raises no reload notice.Instances stay in sync: Instances mounted together (a hidden <mds-pref controller> and a visible settings panel) share the applied mode: a pick in one is mirrored by the others, which neither apply it again nor emit mdsPrefChange. A pref-mode-* class written on <html> by other code is mirrored the same way.Safari fallback: On Safari the control disables itself and forces mode to light, since the transition overlay technique is unsupported there.System mode: The system choice follows the OS prefers-color-scheme media query to resolve the effective light/dark scheme.
Properties & Visual Configurations
mode: Sets and reflects the active mode (light, dark, system). Leave it unset to inherit the persisted/default mode; set it explicitly to force a starting mode.transition: Controls the visual switch between schemes. Use smooth (default) for a fading neutral overlay that flips the mode mid-fade, flash for an instant switch with a brief overlay pulse, or none to apply the new mode with no overlay animation. The overlay timing and z-index are tunable through --mds-pref-mode-overlay-* CSS custom properties.size: Sizes the nested tab items (sm / md). The parent <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 it here (with the same value on the sibling preferences, so the group stays visually consistent).