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

Person Entity with Image

The most common form. Supply src for the avatar image and put the entity name in the default slot. Use <mds-text> with typography="h6" for the primary label so typography tokens are applied consistently.

<mds-entity src="/avatars/mario-rossi.png">
  <mds-text truncate="word" typography="h6">Mario Rossi</mds-text>
</mds-entity>

Entity with Initials Fallback

When no image is available, provide initials instead of src. The avatar chip renders the initials text.

<mds-entity initials="mr">
  <mds-text truncate="word" typography="h6">Mario Rossi</mds-text>
</mds-entity>

Entity with Icon

Use icon for non-person entities (locations, files, organizations). Reference icons by their slug from the Magma icon library.

<mds-entity icon="mi/baseline/location-on">
  <mds-text truncate="word" typography="h6">Maggioli Headquarters</mds-text>
</mds-entity>

Secondary Details via detail Slot

Project additional information (role, email, status) into the detail slot. It renders below the primary name in a subdued color. Use <mds-text typography="caption"> for plain text details.

<mds-entity src="/avatars/giulia-bianchi.png">
  <mds-text truncate="word" typography="h6">Giulia Bianchi</mds-text>
  <mds-text truncate="word" slot="detail" typography="caption">giulia@example.com</mds-text>
  <mds-badge slot="detail" variant="success" tone="weak" label="Attiva"></mds-badge>
</mds-entity>

Trailing Action Buttons via action Slot

Use the action slot for icon-only <mds-button> elements. Each button is sized and spaced automatically by the component. Always provide title on icon-only buttons for accessibility.

<mds-entity src="/avatars/luca-verdi.png">
  <mds-text truncate="word" typography="h6">Luca Verdi</mds-text>
  <mds-text truncate="word" slot="detail" typography="caption">luca@example.com</mds-text>
  <mds-button slot="action" icon="mdi/pencil" variant="primary" tone="strong" title="Modifica"></mds-button>
  <mds-button slot="action" icon="mdi/delete" variant="error" tone="strong" title="Elimina"></mds-button>
</mds-entity>

Colored Avatar with variant and tone

Pair variant and tone to color the avatar chip by entity category. tone is limited to strong and weak; variant accepts the full avatar color set.

<!-- Strong fill, primary variant -->
<mds-entity icon="mi/baseline/business" variant="primary" tone="strong">
  <mds-text truncate="word" typography="h6">Divisione Commerciale</mds-text>
</mds-entity>

<!-- Weak tint, warning variant -->
<mds-entity icon="mi/baseline/warning" variant="warning" tone="weak">
  <mds-text truncate="word" typography="h6">Alert configurazione</mds-text>
</mds-entity>

Await / Loading State

Set the await boolean attribute while the entity data is being fetched. The avatar is hidden and a spinner appears in its place. Remove the attribute when loading is complete - do not set await="false".

<mds-entity await icon="mi/baseline/done" variant="success">
  <mds-text truncate="word" typography="h6">Caricamento in corso...</mds-text>
  <mds-text truncate="word" slot="detail" typography="caption">Attendere prego</mds-text>
</mds-entity>

Upload / Async Workflow

Combine await with icon and variant to drive a state machine: show the spinner while uploading, then reveal the result icon when done.

<!-- While uploading -->
<mds-entity await>
  <mds-text truncate="word" typography="h6">Report finanziario 2024.docx</mds-text>
  <mds-text truncate="word" slot="detail" typography="caption">Upload in corso...</mds-text>
  <mds-button slot="action" icon="mi/baseline/cancel" variant="light" title="Annulla upload"></mds-button>
</mds-entity>

<!-- After success -->
<mds-entity icon="mi/baseline/done" variant="success" tone="weak">
  <mds-text truncate="word" typography="h6">Report finanziario 2024.docx</mds-text>
  <mds-text truncate="word" slot="detail" typography="caption">Upload completato con successo</mds-text>
</mds-entity>

Styling Customization

Style the entity only through its documented --mds-entity-* 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 and high-contrast modes keep working. --mds-entity-icon-background and --mds-entity-icon-color paint the avatar only while it has no variant (none set, and no initials, which derive one).

.entity-highlight mds-entity {
  --mds-entity-background: rgb(var(--magma-accent-surface));
  --mds-entity-color: rgb(var(--magma-accent-fg));
  --mds-entity-detail-color: rgb(var(--magma-text-muted));
  --mds-entity-icon-background: rgb(var(--magma-accent-surface-hover));
  --mds-entity-icon-color: rgb(var(--magma-accent-fg));
}