Pref theme<mds-pref-theme>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
cornerShapeenumSpecifies the corner geometry of the whole page: one of the corner-shape keywords, or default. Corner geometry is theme appearance rather than an accessibility preference, which is why it lives here next to the theme name and scheme instead of in mds-pref-mode. Setting it writes data-corner-shape on <html>, where the generated axis picks both the shape and the radius scale tuned for it. Leaving it unset touches nothing. Setting it to default REMOVES the attribute rather than writing today's default into the page, so a project that never chose keeps following the design system when the default changes.
schemeenumSpecifies the theme scheme which can be 'light', 'dark' or 'all' Default is 'all' which means this theme supporto both light and dark. If you set 'light' means this theme support only light mode and will be forced and shown light colors mode only.
sizeenumSets the size of the component items nested inside it
namestringSpecifies the theme name attribute A string representing the theme name, should be a simple string name or kebab kase name. Examples of valid language codes include "magma", "maggioli-editore", etc.
Overview
The <mds-pref-theme> web component is the theme-switcher segment of the Magma accessibility preferences panel, usually a direct child of <mds-pref>. It renders a labelled tab trigger that opens a dropdown of selectable named themes and, when a theme is chosen, 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 theme by itself. What it gives up on its own is in the antipattern docs.Acts as a sub-parent itself: Its own default slot must contain one or more mds-pref-theme-item elements; it drives their selected state so only the active theme is marked selected.Global theme application: Selecting an item applies the theme document-wide: it writes data-theme-name and the pref-theme-scheme-* class on <html>.Persistence and hydration: The current name, scheme and corner shape are persisted and restored across reloads: a stored value outranks the matching prop.Name validation: An invalid theme name (not lowercase kebab-case matching ^[a-z]+(-[a-z]+)*$) throws at runtime when the theme is applied. So do the reserved names light, dark and system (they are mode values) and scheme or scheme-* (they would collide with the pref-theme-scheme-* classes).Events bubbled up: Emits mdsPrefThemeChange with the { name, scheme } detail on each pick, which <mds-pref> listens to in order to lock the <mds-pref-mode> item a scheme-constrained theme forbids. It also emits mdsPrefChange (preference: 'theme', and 'corner-shape' when a corner shape is set) every time it applies them, on load and on each re-render included.Localized label: The “Theme” heading follows the active interface language.Trigger text: The closed control shows the label of the item for the active theme, the same text the open list shows (localize the items, the trigger follows); when no item matches the active theme it shows the label derived from the name (dark-blue -> “Dark blue”).
Properties & Visual Configurations
name: The active theme name (default 'default'); it is overridden at runtime by any persisted value. Use it to declare the initial theme when no preference has been stored yet. The named themes are cool and warm; default is the base theme (agents/theming.md).scheme: Constrains the colour modes of the theme to 'light', 'dark', or 'all' (default). Pick 'all' for themes that ship both light and dark palettes; pick 'light' or 'dark' to force a single mode for a theme offered in one mode only.size: Sets the size ('sm' / 'md') of the nested tab UI. <mds-pref> forwards its own size to every mds-pref-* segment only when that prop changes after load, not from the initial markup: in markup, set it here (with the same value on the sibling segments, so the panel stays visually consistent).cornerShape (attribute corner-shape): The corner geometry of the whole page - round, squircle, bevel, notch, scoop, square, or default. It writes data-corner-shape on <html> and is persisted like the theme; default removes the attribute, and leaving the prop unset touches nothing (agents/theming.md).