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

Full Empty-State Panel

The canonical form. Pair an illustration in the default slot with a heading and description in slot="content", then provide a recovery action in slot="action".

<mds-zero>
  <mds-img src="./assets/illustrations/empty-list.svg"></mds-img>
  <mds-text typography="h5" slot="content">Nessun elemento trovato</mds-text>
  <mds-text typography="detail" slot="content">
    Non ci sono elementi che corrispondono alla tua ricerca.
    Modifica i filtri o crea un nuovo elemento.
  </mds-text>
  <mds-button
    slot="action"
    label="Crea elemento"
    variant="primary"
    tone="strong"
    size="lg"
  ></mds-button>
</mds-zero>

Illustration Only (No Action)

When there is no meaningful recovery action, omit slot="action" entirely. The action zone collapses cleanly.

<mds-zero>
  <mds-img src="./assets/illustrations/no-results.svg"></mds-img>
  <mds-text typography="h5" slot="content">Nessun risultato</mds-text>
  <mds-text typography="detail" slot="content">
    Prova a modificare i criteri di ricerca per trovare cio che cerchi.
  </mds-text>
</mds-zero>

Message Without Illustration

When no illustration asset is available, omit the default slot. The component stacks the content and action zones directly.

<mds-zero>
  <mds-text typography="h5" slot="content">La cartella e vuota</mds-text>
  <mds-text typography="detail" slot="content">
    Carica i tuoi file per iniziare a condividerli con il team.
  </mds-text>
  <mds-button
    slot="action"
    label="Carica file"
    icon="mi/baseline/upload"
    variant="primary"
    tone="strong"
  ></mds-button>
</mds-zero>

Multiple Actions

When two peer actions are offered - for example a primary and a secondary CTA - place both <mds-button> elements in slot="action". The action zone centers and spaces them automatically.

<mds-zero>
  <mds-img src="./assets/illustrations/empty-inbox.svg"></mds-img>
  <mds-text typography="h5" slot="content">Nessun messaggio</mds-text>
  <mds-text typography="detail" slot="content">
    La tua casella e vuota. Inizia una nuova conversazione o invita i tuoi colleghi.
  </mds-text>
  <mds-button
    slot="action"
    label="Nuovo messaggio"
    variant="primary"
    tone="strong"
  ></mds-button>
  <mds-button
    slot="action"
    label="Invita colleghi"
    variant="primary"
    tone="outline"
  ></mds-button>
</mds-zero>

Constraining the Text Block Width

Use --mds-zero-contents-max-width when the panel is wide and the default 400px cap produces too narrow a text column, or when you want a tighter column on a compact layout.

.wide-dashboard mds-zero {
  --mds-zero-contents-max-width: 560px;
}

.compact-sidebar mds-zero {
  --mds-zero-contents-max-width: 280px;
}

Overriding Zone Layout via Shadow Parts

Use ::part(contents) or ::part(actions) only when you need to change the zone’s layout itself - for example aligning the content left inside a side-panel context. Prefer --mds-zero-contents-max-width for width adjustments.

/* Left-align content for a narrow side panel */
.side-panel mds-zero::part(contents) {
  align-items: flex-start;
  text-align: left;
}