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

Basic Theme Chooser

The canonical form. Place <mds-pref-theme> inside <mds-pref> and populate its default slot with one <mds-pref-theme-item> per available theme. The item whose name matches the active theme (the stored choice, or the parent’s name on a first visit) starts as selected. The named themes are cool and warm; default is the base theme.

<mds-pref>
  <mds-pref-theme name="default" scheme="all">
    <mds-pref-theme-item label="Predefinito" name="default" scheme="all"></mds-pref-theme-item>
    <mds-pref-theme-item label="Freddo" name="cool" scheme="all"></mds-pref-theme-item>
    <mds-pref-theme-item label="Caldo" name="warm" scheme="all"></mds-pref-theme-item>
  </mds-pref-theme>
</mds-pref>

Scheme-Constrained Themes

Use scheme="light" or scheme="dark" on a <mds-pref-theme-item> when the theme must be offered in one colour mode only. The parent component propagates the chosen scheme to <html> and forces that mode even if the user’s OS or mode preference asks for the opposite; inside <mds-pref> the forbidden item of <mds-pref-mode> is locked.

<mds-pref>
  <mds-pref-theme name="default" scheme="all">
    <mds-pref-theme-item label="Predefinito" name="default" scheme="all"></mds-pref-theme-item>
    <!-- light only - dark mode will not activate with this item -->
    <mds-pref-theme-item label="Freddo chiaro" name="cool" scheme="light"></mds-pref-theme-item>
    <!-- dark only -->
    <mds-pref-theme-item label="Caldo scuro" name="warm" scheme="dark"></mds-pref-theme-item>
  </mds-pref-theme>
</mds-pref>

Listening for the Change Event

React to the user’s selection via mdsPrefThemeChange. The event detail carries { name, scheme } - use them to update any app-level state that tracks the active theme.

<mds-pref>
  <mds-pref-theme id="theme-chooser" name="default" scheme="all">
    <mds-pref-theme-item label="Predefinito" name="default" scheme="all"></mds-pref-theme-item>
    <mds-pref-theme-item label="Freddo" name="cool" scheme="all"></mds-pref-theme-item>
  </mds-pref-theme>
</mds-pref>

<script>
  document.querySelector('#theme-chooser').addEventListener('mdsPrefThemeChange', (e) => {
    console.log('Tema attivo:', e.detail.name, '- Schema:', e.detail.scheme);
  });
</script>

Declaring the Initial Theme

Use the name prop to declare which theme should be active before the user makes a selection. If localStorage already holds a persisted value it takes precedence; otherwise the component applies name on first render.

<mds-pref>
  <!-- First-visit default is "warm" -->
  <mds-pref-theme name="warm" scheme="all">
    <mds-pref-theme-item label="Predefinito" name="default" scheme="all"></mds-pref-theme-item>
    <mds-pref-theme-item label="Caldo" name="warm" scheme="all"></mds-pref-theme-item>
  </mds-pref-theme>
</mds-pref>

Controlling Item Size

Pass size="sm" when the preferences panel must fit a compact layout. <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.

<mds-pref>
  <mds-pref-theme name="default" scheme="all" size="sm">
    <mds-pref-theme-item label="Predefinito" name="default" scheme="all"></mds-pref-theme-item>
    <mds-pref-theme-item label="Freddo" name="cool" scheme="all"></mds-pref-theme-item>
  </mds-pref-theme>
</mds-pref>

Styling Theme Items

Style theme items only through their documented --mds-pref-theme-item-* CSS custom properties. Set them on the item host or on a parent selector; name a semantic role, rgb(var(--magma-<role>)) (agents/color.md), so the colours follow the mode, the theme and the contrast preference.

mds-pref-theme-item {
  --mds-pref-theme-item-color-background: rgb(var(--magma-surface-inverse));
  --mds-pref-theme-item-color-variant-primary: rgb(var(--magma-accent-emphasis));
}