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

Basic Language Selector Inside mds-pref

The canonical usage. Nest <mds-pref-language> as a direct child of <mds-pref> and populate its default slot with one <mds-pref-language-item> per supported locale. The code attribute on each item must be a valid BCP 47 short tag.

<mds-pref>
  <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="el"></mds-pref-language-item>
  </mds-pref-language>
</mds-pref>

Forcing a Starting Language with set

Pass an explicit BCP 47 tag to set to override the automatic resolution chain. Use this when the application dictates an initial language regardless of the user’s browser setting or persisted preference.

<mds-pref>
  <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="es"></mds-pref-language-item>
  </mds-pref-language>
</mds-pref>

Automatic Language Resolution (default)

Omit set (or pass set="auto") to let the component resolve the active language in priority order: persisted user choice, then the page <html lang> attribute, then navigator.language. This is the right choice for most applications.

<mds-pref>
  <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>

Sizing via size

Use the size prop to size the tab trigger. 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 size on each preference control, with the same value to keep the group consistent.

<mds-pref>
  <mds-pref-language size="sm">
    <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>

Listening for Language Changes

Listen to mdsPrefLanguageChange to react when the user picks a language (for example, to reload the page or re-fetch translated content). The event detail carries the selected language code string. It fires on every pick, also when the picked language is already the active one.

<mds-pref>
  <mds-pref-language id="lang-selector">
    <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>

<script>
  document.querySelector('#lang-selector').addEventListener('mdsPrefLanguageChange', (e) => {
    console.log('Nuova lingua selezionata:', e.detail.language);
    // e.g. reload the page to apply the new locale
    window.location.reload();
  });
</script>

Full Preference Panel with Language

<mds-pref-language> is one of several preference children accepted by <mds-pref>. Compose it alongside the other controls to offer a complete preferences UI.

<mds-pref>
  <mds-pref-mode></mds-pref-mode>
  <mds-pref-contrast></mds-pref-contrast>
  <mds-pref-animation></mds-pref-animation>
  <mds-pref-consumption></mds-pref-consumption>
  <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="el"></mds-pref-language-item>
  </mds-pref-language>
</mds-pref>