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

Basic Language List Inside the Parent

The canonical form. Place one <mds-pref-language-item> per supported language as a direct child of <mds-pref-language>. Set code to a BCP 47 tag that exists in the bundled dictionary; the component resolves the display name automatically.

<mds-pref-language>
  <mds-pref-language-item code="it"></mds-pref-language-item>
  <mds-pref-language-item code="en"></mds-pref-language-item>
  <mds-pref-language-item code="fr"></mds-pref-language-item>
</mds-pref-language>

Pre-selecting the Active Language

Pre-select through the parent, not through selected: <mds-pref-language> marks the item whose code matches its resolved language when it loads, and overwrites any selected written in the markup. Pass the language to the parent’s set (or leave set on auto).

<mds-pref-language set="it">
  <mds-pref-language-item code="it"></mds-pref-language-item>
  <mds-pref-language-item code="en"></mds-pref-language-item>
  <mds-pref-language-item code="de"></mds-pref-language-item>
</mds-pref-language>

Listening for a Language Selection

The item emits mdsPrefLanguageItemSelect with { language: code } when clicked. In most cases you should listen on the parent (mdsPrefLanguageChange) rather than on individual items - but listening on the item directly is valid when you need fine-grained control.

<mds-pref-language>
  <mds-pref-language-item code="it" id="lang-it"></mds-pref-language-item>
  <mds-pref-language-item code="en" id="lang-en"></mds-pref-language-item>
</mds-pref-language>

<script>
  document.querySelectorAll('mds-pref-language-item').forEach((item) => {
    item.addEventListener('mdsPrefLanguageItemSelect', (e) => {
      console.log('Lingua scelta:', e.detail.language);
    });
  });
</script>

Offering a Large Language Set

Add as many items as needed - the parent lists them all in its dropdown. Each item only needs a code; the visible label is derived automatically.

<mds-pref-language>
  <mds-pref-language-item code="it"></mds-pref-language-item>
  <mds-pref-language-item code="en"></mds-pref-language-item>
  <mds-pref-language-item code="es"></mds-pref-language-item>
  <mds-pref-language-item code="fr"></mds-pref-language-item>
  <mds-pref-language-item code="de"></mds-pref-language-item>
  <mds-pref-language-item code="pt"></mds-pref-language-item>
  <mds-pref-language-item code="zh"></mds-pref-language-item>
  <mds-pref-language-item code="ar"></mds-pref-language-item>
</mds-pref-language>

Inside a Full Preferences Panel

<mds-pref-language> and its items compose inside <mds-pref> alongside the other preference controls. Place them as direct children of <mds-pref>.

<mds-pref>
  <mds-pref-mode></mds-pref-mode>
  <mds-pref-contrast></mds-pref-contrast>
  <mds-pref-language>
    <mds-pref-language-item code="it"></mds-pref-language-item>
    <mds-pref-language-item code="en"></mds-pref-language-item>
  </mds-pref-language>
</mds-pref>