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

Basic Usage Inside the Parent

<mds-pref-theme-item> must always be a direct child of <mds-pref-theme>. Each item represents one selectable colour theme; the parent manages selection state so all siblings stay in sync.

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

Auto-Derived Label

Omit label and let the component generate it from name: the first letter is capitalised and hyphens are replaced with spaces. Use this shorthand when the theme name is already human-readable.

<mds-pref-theme name="default" scheme="all">
  <!-- renders "Default", "Cool", "Warm" without explicit label props -->
  <mds-pref-theme-item name="default" scheme="all"></mds-pref-theme-item>
  <mds-pref-theme-item name="cool" scheme="all"></mds-pref-theme-item>
  <mds-pref-theme-item name="warm" scheme="all"></mds-pref-theme-item>
</mds-pref-theme>

Scheme-Specific Themes

Set scheme to "light" or "dark" when a theme must be offered in a single colour mode only. The parent applies the forced mode when the item is selected.

<mds-pref-theme name="default" scheme="all">
  <!-- this theme works in both modes -->
  <mds-pref-theme-item name="default" label="Predefinito" scheme="all"></mds-pref-theme-item>

  <!-- offered light-only; selecting it locks the UI in light mode -->
  <mds-pref-theme-item name="cool" label="Freddo chiaro" scheme="light"></mds-pref-theme-item>

  <!-- offered dark-only; selecting it locks the UI in dark mode -->
  <mds-pref-theme-item name="warm" label="Caldo scuro" scheme="dark"></mds-pref-theme-item>
</mds-pref-theme>

Listening to the Selection Event

Attach a listener for mdsPrefThemeItemSelect when you need to react to a selection at the item level - for example to log analytics. The detail carries { name, scheme }. Normally the parent handles theme application automatically; only listen at this level for side-effects.

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

<script>
  document.querySelectorAll('mds-pref-theme-item').forEach((item) => {
    item.addEventListener('mdsPrefThemeItemSelect', (e) => {
      console.log('Tema selezionato:', e.detail.name, 'schema:', e.detail.scheme);
    });
  });
</script>

Setting the Initially Selected Item

Declare it on the parent, not with selected: when it loads, <mds-pref-theme> marks the item whose name matches the active theme (the stored choice, or its own name on a first visit) and overwrites any selected written in the markup.

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

CSS Customization via Documented Properties

Override the swatch colours only through the documented --mds-pref-theme-item-* CSS custom properties. Set them on the host element or a parent selector and name a semantic role for the colour values, rgb(var(--magma-<role>)) (agents/color.md), so mode, theme and contrast keep working.

/* override the colour preview dots of one theme item */
mds-pref-theme-item[name="warm"] {
  --mds-pref-theme-item-color-variant-primary: rgb(var(--magma-accent-emphasis-hover));
  --mds-pref-theme-item-color-status-success: rgb(var(--magma-success-emphasis));
  --mds-pref-theme-item-color-status-warning: rgb(var(--magma-warning-emphasis));
  --mds-pref-theme-item-color-status-error: rgb(var(--magma-danger-emphasis));
  --mds-pref-theme-item-color-background: rgb(var(--magma-wash-strong));
}