Common incorrect uses of <mds-dropdown>. 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 Place the Dropdown Deep Inside a Scroll or Stacking Context

Nesting <mds-dropdown> inside a transformed, sticky, or overflow: hidden ancestor breaks floating positioning and backdrop rendering. Place it as close to <body> as the page structure allows, or switch to strategy="fixed".

<!-- INCORRECT -->
<div style="overflow: hidden; position: relative;">
  <mds-button id="trigger" label="Apri" variant="primary"></mds-button>
  <mds-dropdown target="#trigger" backdrop>
    <mds-text>Contenuto</mds-text>
  </mds-dropdown>
</div>

<!-- CORRECT -->
<div style="overflow: hidden; position: relative;">
  <mds-button id="trigger" label="Apri" variant="primary"></mds-button>
</div>
<mds-dropdown target="#trigger" strategy="fixed" backdrop>
  <mds-text>Contenuto</mds-text>
</mds-dropdown>

Do Not Use visible="false" to Close the Dropdown

visible is a boolean prop. The component reads the string "false" as false and drops the attribute when it renders, but until then the attribute is in the DOM and attribute selectors (mds-dropdown[visible]) match it. Remove the attribute or set the property to false in JavaScript to close it.

<!-- INCORRECT -->
<mds-dropdown target="#btn" visible="false">
  <mds-text>Contenuto</mds-text>
</mds-dropdown>

<!-- CORRECT -->
<mds-dropdown target="#btn">
  <mds-text>Contenuto</mds-text>
</mds-dropdown>

// CORRECT - closing programmatically
document.querySelector('mds-dropdown').visible = false;

Do Not Listen for Native click on the Target Instead of Dropdown Events

The dropdown manages its own interaction and emits mdsDropdownVisible, mdsDropdownHide, and mdsDropdownChange. Attaching a raw click listener to the caller can interfere with inside-click handling and may fire before the dropdown has updated its state.

<!-- INCORRECT -->
<mds-button id="btn-info" label="Info" variant="primary"></mds-button>
<mds-dropdown target="#btn-info">...</mds-dropdown>

<script>
  // raw native event on the caller - races with dropdown internals
  document.querySelector('#btn-info').addEventListener('click', () => {
    console.log('cliccato');
  });
</script>

<!-- CORRECT -->
<mds-button id="btn-info" label="Info" variant="primary"></mds-button>
<mds-dropdown id="dd-info" target="#btn-info">...</mds-dropdown>

<script>
  document.querySelector('#dd-info').addEventListener('mdsDropdownVisible', (e) => {
    console.log('dropdown aperto', e.detail.visible);
  });
</script>

Do Not Use target Without a Matching Element in the DOM

target is resolved with querySelector at componentDidLoad time. If the selector does not match any element the dropdown has no caller and cannot position or open itself. Always verify the id is present in the DOM before the component loads.

<!-- INCORRECT - typo: button has id "btn-salva", target points to "#salva" -->
<mds-button id="btn-salva" label="Salva" variant="primary"></mds-button>
<mds-dropdown target="#salva">
  <mds-text>Opzioni di salvataggio</mds-text>
</mds-dropdown>

<!-- CORRECT -->
<mds-button id="btn-salva" label="Salva" variant="primary"></mds-button>
<mds-dropdown target="#btn-salva">
  <mds-text>Opzioni di salvataggio</mds-text>
</mds-dropdown>

Do Not Use <mds-button-dropdown> and <mds-dropdown> Interchangeably

mds-button-dropdown is a compound component that already embeds a trigger button and a dropdown. Use it for a simple action-button-plus-menu. Use <mds-dropdown> directly only when the caller is not an mds-button, or when you need full control over the trigger element.

<!-- INCORRECT - re-implementing what mds-button-dropdown already does -->
<mds-button id="btn-azioni" label="Azioni" icon="mi/baseline/expand-more" variant="primary"></mds-button>
<mds-dropdown target="#btn-azioni">
  <mds-button label="Modifica" variant="dark" tone="text"></mds-button>
  <mds-button label="Elimina" variant="error" tone="text"></mds-button>
</mds-dropdown>

<!-- CORRECT - use the dedicated compound component -->
<mds-button-dropdown label="Azioni" variant="primary">
  <mds-button label="Modifica" variant="dark" tone="text"></mds-button>
  <mds-button label="Elimina" variant="error" tone="text"></mds-button>
</mds-button-dropdown>

Do Not Customize via Undocumented Shadow Internals

The supported customization surface is the --mds-dropdown-* CSS custom properties. Targeting internal elements via ::part() on non-documented parts, >>>, or class-name selectors couples your code to the Shadow DOM structure and breaks on any internal refactor.

/* INCORRECT */
mds-dropdown::part(panel) {
  border: 2px solid red;
}
mds-dropdown >>> .arrow {
  display: none;
}

/* CORRECT */
mds-dropdown {
  --mds-dropdown-background: rgb(var(--magma-surface-overlay));
  --mds-dropdown-z-index: 6000;
}