Common incorrect uses of <mds-pref-language>. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in agents/anti-patterns.md - they apply here too but are not repeated.

Do Not Use Outside mds-pref

<mds-pref-language> is a compound child designed to live inside <mds-pref>. As a standalone widget it still applies and persists the language, but it leaves the preference group: <mds-pref> forwards size changes to its mds-pref-* children and listens to their mdsPrefChange for the reload-required notice.

<!-- INCORRECT -->
<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>

<!-- CORRECT -->
<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>

Do Not Slot Arbitrary HTML Instead of mds-pref-language-item

The default slot accepts only <mds-pref-language-item> elements. Slotting raw <button>, <li>, or other elements bypasses the selection orchestration and event wiring the parent depends on.

<!-- INCORRECT -->
<mds-pref>
  <mds-pref-language>
    <button>Italiano</button>
    <button>English</button>
  </mds-pref-language>
</mds-pref>

<!-- CORRECT -->
<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>

Do Not Pass an Unrecognized Language Code to set

The set prop must be either "auto" or a valid two-letter BCP 47 tag (xx or xx-XX). Any other value - including full locale strings like "italiano", ISO 639-2 three-letter codes, or malformed strings - throws an error at runtime.

<!-- INCORRECT -->
<mds-pref-language set="italiano">...</mds-pref-language>
<mds-pref-language set="en_US">...</mds-pref-language>

<!-- CORRECT -->
<mds-pref-language set="it">...</mds-pref-language>
<mds-pref-language set="en">...</mds-pref-language>
<mds-pref-language set="es-ES">...</mds-pref-language>

Do Not Set selected Manually on mds-pref-language-item

The parent <mds-pref-language> manages the selected state of each item automatically based on the active language: when it loads it marks only the item whose code matches, and on each pick it clears the siblings. A selected written in the markup is overwritten on load; one set later from script leaves the visual selection out of step with the active language.

<!-- INCORRECT -->
<mds-pref>
  <mds-pref-language set="it">
    <mds-pref-language-item code="it" selected></mds-pref-language-item>
    <mds-pref-language-item code="en"></mds-pref-language-item>
  </mds-pref-language>
</mds-pref>

<!-- CORRECT - the parent derives selection from `set` -->
<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>
</mds-pref>

Do Not Listen to mdsPrefLanguageItemSelect Instead of mdsPrefLanguageChange

mdsPrefLanguageItemSelect is the item’s own event, emitted by <mds-pref-language-item> and consumed by its parent. Application code should listen to mdsPrefLanguageChange on <mds-pref-language>: one listener for the whole list, fired after the parent has committed the selection (the language is applied right after it, so read it from e.detail.language).

<!-- INCORRECT -->
<script>
  document.querySelector('mds-pref-language-item').addEventListener('mdsPrefLanguageItemSelect', (e) => {
    console.log(e.detail.language);
  });
</script>

<!-- CORRECT -->
<script>
  document.querySelector('mds-pref-language').addEventListener('mdsPrefLanguageChange', (e) => {
    console.log(e.detail.language);
  });
</script>

Do Not Set Size via CSS Instead of the size Prop

The size prop is the only supported way to resize the internal tab trigger. Overriding dimensions with inline styles or CSS custom properties not listed in the component’s documented surface couples your code to internal implementation details.

/* INCORRECT */
mds-pref-language mds-tab-item {
  font-size: 10px;
}

<!-- CORRECT -->
<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>