Correct and idiomatic ways to use the <mds-button> 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.

Text Button via label Prop

The canonical form. Use the label prop for the button’s text; it is rendered inside the button and is its accessible name, so screen readers work without extra wiring.

<mds-button label="Conferma azione" variant="primary" tone="strong"></mds-button>

Variant and Tone for Emphasis

Pair the same variant with a different tone to express importance. Do not invent custom colors to dim or saturate.

<!-- High emphasis: primary call to action -->
<mds-button label="Salva" variant="primary" tone="strong"></mds-button>

<!-- Medium emphasis: supporting action -->
<mds-button label="Modifica" variant="primary" tone="outline"></mds-button>

<!-- Low emphasis: in-text or destructive secondary action -->
<mds-button label="Annulla" variant="error" tone="text"></mds-button>

Sizing

Use the size prop. Do not override dimensions with inline width / height.

<mds-button label="Small" size="sm" variant="primary"></mds-button>
<mds-button label="Medium" size="md" variant="primary"></mds-button>
<mds-button label="Large" size="lg" variant="primary"></mds-button>
<mds-button label="Extra large" size="xl" variant="primary"></mds-button>

Button with Icon

Reference icons by their filename slug (no .svg extension). icon-position defaults to left; set it to right for forward-motion CTAs.

<!-- Left icon (default) -->
<mds-button label="Aggiungi" icon="mi/baseline/add" variant="primary" tone="weak"></mds-button>

<!-- Right icon -->
<mds-button
  label="Avanti"
  icon="mi/baseline/arrow-forward"
  icon-position="right"
  variant="primary"
></mds-button>

Icon-Only Button

Omit label and provide aria-label (or title) explicitly. Without one, the component names the button after the last segment of the icon slug (“delete”), which names the icon, not the action.

<mds-button
  icon="mi/baseline/delete"
  aria-label="Elimina elemento"
  variant="error"
  tone="text"
></mds-button>

When an mds-tooltip shows the name of the button, let the tooltip be the name with relation="label" instead: the button then needs no aria-label, and gets no title from the icon slug.

<mds-button id="elimina-btn" icon="mi/baseline/delete" variant="error" tone="text"></mds-button>
<mds-tooltip target="#elimina-btn" relation="label">Elimina elemento</mds-tooltip>

Hyperlink via href

Setting href renders a real link: the browser follows it, in a new tab on a modifier or middle click, and the context menu offers the link actions. Use target="blank" to open in a new tab on a plain click too; default is self.

<mds-button
  label="Visita il sito"
  href="https://example.com"
  target="blank"
  variant="primary"
  tone="outline"
></mds-button>

Client-Side Routing via href

In a single-page app keep href for the link it gives (new tab, context menu, crawlers) and register the router once with NavigationService, from @maggioli-design-system/magma/services: every component link is then routed on the client on a plain click, with no listener per button. A modifier or middle click, target="blank" and a link to another origin stay with the browser; return false from the handler for a link the browser is to load.

<mds-button label="Pratiche" href="/pratiche" variant="primary" tone="text"></mds-button>

<script type="module">
  import { NavigationService } from '@maggioli-design-system/magma/services';

  NavigationService.setHandler((href) => router.navigate(href));
</script>

Without a registered router, cancel the click on the button and route by hand: the component honours preventDefault(). Leave a modifier click alone, so that the browser opens the link in a new tab.

<script>
  document.querySelector('mds-button[href]').addEventListener('click', (event) => {
    if (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) return;
    event.preventDefault();
    router.navigate(event.currentTarget.href);
  });
</script>

Async Loading via await

Set the await boolean attribute while a request is in flight. The component renders an inline spinner, blocks pointer activation, and sets aria-busy="true". Remove the attribute when done - do not set await="false".

<mds-button label="Salvataggio in corso..." await variant="primary"></mds-button>

Form Participation

<mds-button> is form-associated. Inside a <form> it natively triggers submit (type="submit", default) or reset (type="reset"). Use type="button" for any action that must not submit the form.

<form action="/save" method="post">
  <mds-input-field label="Titolo">
    <mds-input name="title"></mds-input>
  </mds-input-field>

  <mds-button type="submit" label="Invia" variant="primary" tone="strong"></mds-button>
  <mds-button type="reset" label="Reimposta" variant="dark" tone="outline"></mds-button>
  <mds-button type="button" label="Anteprima" variant="primary" tone="text"></mds-button>
</form>

Several Actions That Submit One Form

Give the buttons the same name and a different value, as with native submit buttons: the receiver reads which action was chosen from name.

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

  <!-- the receiver gets action=send or action=draft -->
  <mds-button name="action" value="send" label="Invia" variant="primary"></mds-button>
  <mds-button name="action" value="draft" label="Salva come bozza" tone="outline"></mds-button>
</form>

When your code handles the submit, build the form data with event.submitter, as for a native button: it carries the name / value of the button that was clicked.

form.addEventListener('submit', (event) => {
  event.preventDefault();
  const data = new FormData(form, event.submitter);
  data.get('action'); // 'send' or 'draft'
});

To show one action and keep the others in a menu, use mds-button-dropdown with type="submit": its primary action and its menu items send name / value the same way.

Notification Badge via Named Slot

The notification slot accepts an <mds-notification>. This is the documented exception to the default-slot-is-text rule.

<mds-button label="Notifiche" icon="mi/baseline/notifications" variant="primary" tone="weak">
  <mds-notification slot="notification" value="12"></mds-notification>
</mds-button>

SSO Identity Variants

variant="google" and variant="apple" apply the brand-correct chrome for SSO entry points. Do not reuse them for non-SSO buttons.

<mds-button label="Accedi con Google" variant="google"></mds-button>
<mds-button label="Accedi con Apple" variant="apple"></mds-button>

Styling Customization

Style the button only through its documented --mds-button-* CSS custom properties. Set them on the host or a parent selector; use the semantic color roles via rgb(var(--magma-<role>)) so dark mode, named themes and high contrast keep working.

.featured-action mds-button {
  --mds-button-background: rgb(var(--magma-accent-emphasis));
  --mds-button-color: rgb(var(--magma-accent-on-emphasis));
  --mds-button-radius: var(--magma-radius-lg);
  --mds-button-gap: calc(var(--spacing) * 300);
}