Common incorrect uses of <mds-button-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 Put the Label in the Default Slot

The default slot feeds the <mds-dropdown> panel, not the button label. Text placed in the slot ends up as menu content, not as the button’s visible text. Use the label prop.

<!-- INCORRECT -->
<mds-button-dropdown variant="primary" tone="strong">
  Salva
</mds-button-dropdown>

<!-- CORRECT -->
<mds-button-dropdown label="Salva" variant="primary" tone="strong">
  <mds-button variant="dark" tone="text" label="Salva come bozza"></mds-button>
</mds-button-dropdown>

Do Not Slot Non-Button Content as Menu Items

The dropdown panel is designed for mds-button elements. Slotting raw <button>, <a>, or arbitrary HTML bypasses the Magma theming, focus styles and button API (icon, await, disabled) of the menu entries.

<!-- INCORRECT -->
<mds-button-dropdown label="Esporta" variant="primary" tone="weak">
  <button onclick="exportPDF()">PDF</button>
  <a href="/export/csv">CSV</a>
</mds-button-dropdown>

<!-- CORRECT -->
<mds-button-dropdown label="Esporta" variant="primary" tone="weak">
  <mds-button variant="dark" tone="text" label="Esporta PDF" icon="mi/baseline/picture-as-pdf"></mds-button>
  <mds-button variant="dark" tone="text" label="Esporta CSV" icon="mi/baseline/table-chart"></mds-button>
</mds-button-dropdown>

Do Not Count on the Default type to Submit a Form

Unlike <mds-button>, the component defaults to type="button": inside a form, the primary action submits nothing until you set type="submit".

<!-- INCORRECT: the primary action does not submit -->
<form action="/mail" method="post">
  <mds-button-dropdown name="action" value="send" label="Invia">
    <mds-button name="action" value="draft" variant="dark" tone="text" label="Salva come bozza"></mds-button>
  </mds-button-dropdown>
</form>

<!-- CORRECT -->
<form action="/mail" method="post">
  <mds-button-dropdown type="submit" name="action" value="send" label="Invia">
    <mds-button name="action" value="draft" variant="dark" tone="text" label="Salva come bozza"></mds-button>
  </mds-button-dropdown>
</form>

Do Not Submit the Form from a click Listener

A click listener on the component also runs for the menu items, whose clicks bubble to it: picking a menu item that submits (“Salva come bozza”) submits the form twice, once with its name / value and once without, and the receiver cannot tell which action was chosen. Use type="submit" with name / value.

<!-- INCORRECT -->
<mds-button-dropdown id="send" label="Invia"></mds-button-dropdown>
<script>
  document.getElementById('send').addEventListener('click', () => form.requestSubmit());
</script>

<!-- CORRECT -->
<mds-button-dropdown type="submit" name="action" value="send" label="Invia"></mds-button-dropdown>

Do Not Listen to click for the Primary Action

A click on the component also comes from the menu items, whose clicks bubble to it: the primary action would run whenever the user picks an entry of the menu. Listen for mdsButtonDropdownClick, which only the primary action emits.

// INCORRECT: also runs for "Salva come copia"
dropdown.addEventListener('click', () => save());

// CORRECT
dropdown.addEventListener('mdsButtonDropdownClick', () => save());

Do Not Leave a Menu Item That Must Not Submit on the Default type

The menu items are slotted <mds-button>, whose type defaults to 'submit': inside a form, an item that runs your own code (a preview, a copy) submits the form too. Give it type="button".

<!-- INCORRECT: "Anteprima" submits the form -->
<mds-button-dropdown type="submit" name="action" value="send" label="Invia">
  <mds-button variant="dark" tone="text" label="Anteprima"></mds-button>
</mds-button-dropdown>

<!-- CORRECT -->
<mds-button-dropdown type="submit" name="action" value="send" label="Invia">
  <mds-button type="button" variant="dark" tone="text" label="Anteprima"></mds-button>
</mds-button-dropdown>

Do Not Use Unsupported tone Values

<mds-button-dropdown> accepts ToneMinimalVariantType, which is strong and weak only. Passing outline, text, or box is not valid for this component: the value reaches the internal buttons unchecked, without the split-button styling that only strong and weak have.

<!-- INCORRECT -->
<mds-button-dropdown label="Azione" variant="primary" tone="outline"></mds-button-dropdown>
<mds-button-dropdown label="Azione" variant="primary" tone="text"></mds-button-dropdown>

<!-- CORRECT -->
<mds-button-dropdown label="Azione" variant="primary" tone="strong">
  <mds-button variant="dark" tone="text" label="Opzione"></mds-button>
</mds-button-dropdown>
<mds-button-dropdown label="Azione" variant="primary" tone="weak">
  <mds-button variant="dark" tone="text" label="Opzione"></mds-button>
</mds-button-dropdown>

Do Not Try to Customize the Chevron Icon

The chevron trigger icon is internal and fixed. There is no prop to change it. Do not attempt to override it with CSS property hacks or shadow-DOM selectors.

/* INCORRECT */
mds-button-dropdown .dropdown-action mds-icon {
  content: url('custom-arrow.svg');
}

/* CORRECT - style only through documented custom properties and the dropdown part */
mds-button-dropdown {
  --mds-button-dropdown-radius: var(--magma-radius-md);
}
mds-button-dropdown::part(dropdown) {
  box-shadow: var(--shadow-lg);
}

Do Not Set Boolean Attributes to "false"

await, disabled, and active are boolean attributes. 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-button-dropdown[disabled]) match it. Remove the attribute to turn it off.

<!-- INCORRECT -->
<mds-button-dropdown label="Invia" await="false" disabled="false" variant="primary"></mds-button-dropdown>

<!-- CORRECT -->
<mds-button-dropdown label="Invia" variant="primary" tone="strong">
  <mds-button variant="dark" tone="text" label="Invia come bozza"></mds-button>
</mds-button-dropdown>