Correct and idiomatic ways to use the <mds-button-dropdown> component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in agents/variants.md and the shared component rules in agents/conventions.md.

Basic Split Button with Menu Items

The canonical form: a label prop for the primary action and one or more mds-button elements in the default slot as menu choices. Give the slot items variant="dark" tone="text" to keep them visually neutral inside the dropdown panel.

<mds-button-dropdown label="Salva come bozza" variant="success" tone="weak">
  <mds-button icon="mi/baseline/send" variant="dark" tone="text" label="Invia subito"></mds-button>
  <mds-button icon="mi/baseline/delete" variant="dark" tone="text" label="Elimina"></mds-button>
</mds-button-dropdown>

Variant and Tone for Emphasis

Use variant to express meaning and tone to express weight - the same pair applies to both internal buttons automatically.

<!-- High emphasis: primary action -->
<mds-button-dropdown label="Pubblica" variant="primary" tone="strong">
  <mds-button variant="dark" tone="text" label="Pubblica come bozza"></mds-button>
  <mds-button variant="dark" tone="text" label="Pianifica pubblicazione"></mds-button>
</mds-button-dropdown>

<!-- Status emphasis: destructive action group -->
<mds-button-dropdown label="Elimina voce" variant="error" tone="weak">
  <mds-button variant="dark" tone="text" label="Elimina e archivia"></mds-button>
  <mds-button variant="dark" tone="text" label="Annulla eliminazione"></mds-button>
</mds-button-dropdown>

Sizing

Use the size prop. Both internal buttons track it automatically.

<mds-button-dropdown label="Azione" size="sm" variant="primary" tone="strong">
  <mds-button variant="dark" tone="text" label="Opzione A"></mds-button>
</mds-button-dropdown>

<mds-button-dropdown label="Azione" size="md" variant="primary" tone="strong">
  <mds-button variant="dark" tone="text" label="Opzione A"></mds-button>
</mds-button-dropdown>

<mds-button-dropdown label="Azione" size="lg" variant="primary" tone="strong">
  <mds-button variant="dark" tone="text" label="Opzione A"></mds-button>
</mds-button-dropdown>

<mds-button-dropdown label="Azione" size="xl" variant="primary" tone="strong">
  <mds-button variant="dark" tone="text" label="Opzione A"></mds-button>
</mds-button-dropdown>

Primary Action with an Icon

Supply the icon prop to add an icon to the primary action button. The chevron trigger icon is fixed and not configurable.

<mds-button-dropdown
  label="Carica documento"
  icon="mi/baseline/upload"
  variant="primary"
  tone="weak"
>
  <mds-button variant="dark" tone="text" label="Carica da URL"></mds-button>
  <mds-button variant="dark" tone="text" label="Carica da Drive"></mds-button>
</mds-button-dropdown>

Async Loading via await

Set the await boolean attribute while a request is in flight. Both the action button and the chevron trigger become unavailable simultaneously. Remove the attribute when done - do not set await="false".

<mds-button-dropdown label="Salvataggio in corso..." await variant="primary" tone="strong">
  <mds-button variant="dark" tone="text" label="Salva e chiudi"></mds-button>
  <mds-button variant="dark" tone="text" label="Salva come copia"></mds-button>
</mds-button-dropdown>

Disabled State

The disabled attribute blocks both halves of the control together.

<mds-button-dropdown label="Invia richiesta" disabled variant="primary" tone="strong">
  <mds-button variant="dark" tone="text" label="Invia in bozza"></mds-button>
</mds-button-dropdown>

Primary Action Handled in JavaScript

Listen for mdsButtonDropdownClick to run the primary action: it comes from the primary action only, from a click or the keyboard, and not while the component is disabled or awaiting. Handle each menu item with its own click.

<mds-button-dropdown id="save" label="Salva" variant="primary">
  <mds-button id="save-copy" variant="dark" tone="text" label="Salva come copia"></mds-button>
</mds-button-dropdown>

<script>
  document.getElementById('save').addEventListener('mdsButtonDropdownClick', () => save());
  document.getElementById('save-copy').addEventListener('click', () => saveCopy());
</script>

Several Actions That Submit One Form

Set type="submit" on the component and give the primary action and the menu items the same name with a different value: each action submits the form, and the receiver reads which one was chosen from name, as with native submit buttons. Give type="button" to the menu items that must not submit.

<form action="/mail" method="post">
  <mds-input-field label="Oggetto">
    <mds-input name="subject"></mds-input>
  </mds-input-field>

  <!-- the receiver gets action=send, action=draft or action=schedule -->
  <mds-button-dropdown type="submit" name="action" value="send" label="Invia" variant="primary">
    <mds-button name="action" value="draft" variant="dark" tone="text" label="Salva come bozza"></mds-button>
    <mds-button name="action" value="schedule" variant="dark" tone="text" label="Invio programmato"></mds-button>
    <mds-button type="button" variant="dark" tone="text" label="Anteprima"></mds-button>
  </mds-button-dropdown>
</form>

When your code handles the submit, build the form data with event.submitter, as for mds-button: new FormData(form, event.submitter).

Hyperlink Split Button via href

href and target on the component are forwarded to both internal buttons, the chevron included: a click on the chevron navigates as well as opening the menu. Keep href off the component, handle the primary action with mdsButtonDropdownClick, and put the links on the menu items (target="blank" opens them in a new tab).

<mds-button-dropdown
  label="Apri documento"
  variant="primary"
  tone="weak"
>
  <mds-button href="https://example.com/doc/edit" target="blank" variant="dark" tone="text" label="Modifica"></mds-button>
  <mds-button href="https://example.com/doc/history" target="blank" variant="dark" tone="text" label="Cronologia"></mds-button>
</mds-button-dropdown>

Styling Customization

Style the component through its documented --mds-button-dropdown-* CSS custom properties or the dropdown shadow part. Use the semantic color roles via rgb(var(--magma-<role>)) so dark mode and named themes keep working.

.custom-toolbar mds-button-dropdown {
  --mds-button-dropdown-radius: var(--magma-radius-md);
}

/* Style the dropdown panel surface through the documented shadow part */
.custom-toolbar mds-button-dropdown::part(dropdown) {
  box-shadow: var(--shadow-lg);
}