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

Toolbar of Icon-Only Actions

The primary use case. Group icon-only <mds-button> elements that act on the same target - a text selection, a table row, or an editor surface. Each button must carry an explicit aria-label because no visible label is present.

<mds-button-group>
  <mds-button icon="mi/baseline/format-bold" aria-label="Grassetto" variant="dark" tone="text"></mds-button>
  <mds-button icon="mi/baseline/format-italic" aria-label="Corsivo" variant="dark" tone="text"></mds-button>
  <mds-button icon="mi/baseline/format-underlined" aria-label="Sottolineato" variant="dark" tone="text"></mds-button>
</mds-button-group>

Segmented Set of Labelled Actions

Use labelled buttons when the actions benefit from visible text - for example a primary / secondary / destructive trio at the bottom of a form section.

<mds-button-group>
  <mds-button label="Salva" variant="primary" tone="strong"></mds-button>
  <mds-button label="Annulla" variant="dark" tone="outline"></mds-button>
</mds-button-group>

Mixed Emphasis Within a Group

Pair a high-emphasis primary button with lower-emphasis supporting actions. Keep the same variant family and vary only the tone so the group reads as a cohesive cluster, not a random set of buttons.

<mds-button-group>
  <mds-button label="Pubblica" variant="primary" tone="strong"></mds-button>
  <mds-button label="Salva come bozza" variant="primary" tone="outline"></mds-button>
  <mds-button label="Elimina" variant="error" tone="text"></mds-button>
</mds-button-group>

Inside a Toolbar or Action Bar

<mds-button-group> is inline-flex by default, so multiple groups sit naturally beside other inline controls in a toolbar without extra CSS.

<div class="toolbar">
  <mds-button-group>
    <mds-button icon="mi/baseline/undo" aria-label="Annulla" variant="dark" tone="text"></mds-button>
    <mds-button icon="mi/baseline/redo" aria-label="Ripristina" variant="dark" tone="text"></mds-button>
  </mds-button-group>

  <mds-button-group>
    <mds-button icon="mi/baseline/format-bold" aria-label="Grassetto" variant="dark" tone="text"></mds-button>
    <mds-button icon="mi/baseline/format-italic" aria-label="Corsivo" variant="dark" tone="text"></mds-button>
    <mds-button icon="mi/baseline/format-underlined" aria-label="Sottolineato" variant="dark" tone="text"></mds-button>
  </mds-button-group>
</div>

Including a <mds-button-dropdown> in the Group

The default slot accepts any <mds-button> or <mds-button-dropdown> sibling component. Place the dropdown last or first depending on visual priority.

<mds-button-group>
  <mds-button label="Esporta CSV" variant="primary" tone="weak"></mds-button>
  <mds-button-dropdown label="Altre opzioni" variant="primary" tone="weak">
    <mds-button variant="dark" tone="text" label="Esporta PDF"></mds-button>
    <mds-button variant="dark" tone="text" label="Esporta Excel"></mds-button>
  </mds-button-dropdown>
</mds-button-group>

Disabled Buttons Inside a Group

Disable individual buttons with the disabled boolean attribute. Never use disabled="false" - remove the attribute to re-enable. The group itself has no disabled prop.

<mds-button-group>
  <mds-button label="Approva" variant="success" tone="strong"></mds-button>
  <mds-button label="Rifiuta" variant="error" tone="outline" disabled></mds-button>
</mds-button-group>