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

Basic Action Bar

The canonical form. Place mds-button elements in the default slot and show the bar by setting visible. The bar docks to the bottom-right corner of the viewport by default.

<mds-status-bar visible>
  <mds-button id="cancel" variant="dark" tone="weak">Annulla</mds-button>
  <mds-button id="confirm" variant="primary" tone="strong">Conferma azione</mds-button>
</mds-status-bar>

Showing a Contextual Description

Use description to render an optional caption beside the slotted actions when the context is not obvious from the buttons alone.

<mds-status-bar visible description="Stai modificando 4 elementi">
  <mds-button variant="dark" tone="weak">Annulla</mds-button>
  <mds-button variant="primary" tone="strong">Salva</mds-button>
</mds-status-bar>

Controlling Position

Use the position prop to anchor the bar to the bottom-left or to the bottom-center of the viewport. The default is 'bottom-right'.

<!-- Bottom-left -->
<mds-status-bar visible position="bottom-left" description="Selezione attiva">
  <mds-button variant="error" tone="outline">Elimina selezionati</mds-button>
</mds-status-bar>

<!-- Centered bottom -->
<mds-status-bar visible position="bottom" description="Azione in corso">
  <mds-button variant="primary" tone="strong">Applica</mds-button>
</mds-status-bar>

Programmatic Show / Hide

Toggle the bar imperatively: set visible = true to show it and call hide() to dismiss it (visible = false works too: the component normalizes it to undefined). In markup remove the attribute, never write visible="false".

<mds-button id="edit-trigger">Modifica elementi</mds-button>

<mds-status-bar id="bar" description="Stai modificando la selezione">
  <mds-button id="cancel" variant="dark" tone="weak">Annulla</mds-button>
  <mds-button id="save" variant="primary" tone="strong">Salva modifiche</mds-button>
</mds-status-bar>

<script>
  const bar = document.getElementById('bar');
  document.getElementById('edit-trigger').addEventListener('click', () => {
    bar.visible = true;
  });
  document.getElementById('cancel').addEventListener('click', () => {
    bar.hide();
  });
</script>

Async Confirm Flow

Show an in-flight state on the confirm button using await, then call hide() when the operation completes. The cancel button should be disabled while the request is in progress.

<mds-status-bar id="bar" visible description="Stai modificando 3 elementi">
  <mds-button id="cancel" variant="dark" tone="weak">Annulla</mds-button>
  <mds-button id="confirm" variant="primary" tone="strong">Conferma</mds-button>
</mds-status-bar>

<script>
  const bar = document.getElementById('bar');
  const cancel = document.getElementById('cancel');
  const confirm = document.getElementById('confirm');

  confirm.addEventListener('click', async () => {
    cancel.disabled = true;
    confirm.await = true;
    confirm.label = 'Salvataggio in corso...';
    await saveChanges();
    bar.hide();
  });
</script>

Locking Body Scroll

Set overflow="auto" to prevent the page from scrolling while the status bar is open. The default 'manual' leaves the body scrollable.

<mds-status-bar visible overflow="auto" description="Salvataggio in corso">
  <mds-button variant="dark" tone="weak">Annulla</mds-button>
  <mds-button variant="primary" tone="strong" await>Salva</mds-button>
</mds-status-bar>

Styling Customization

Customize the bar only through its documented --mds-status-bar-* CSS custom properties and the exposed ::part() names (status-bar, status-bar-area, actions). Use semantic color roles via rgb(var(--magma-<role>)) so dark mode keeps working.

mds-status-bar {
  --mds-status-bar-max-width: 700px;
  --mds-status-bar-backdrop: rgb(var(--magma-shadow-ink) / 0.2);
  --mds-status-bar-backdrop-filter: blur(6px);
}

mds-status-bar::part(status-bar) {
  border: 1px solid rgb(var(--magma-border-default));
}