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

Static Tag (Label Only)

The simplest form. Use the required label prop to display a read-only tag. With no interaction props the chip is passive and non-focusable.

<mds-chip label="In lavorazione" variant="warning" tone="strong"></mds-chip>

Variant and Tone for Semantic Emphasis

Pair the same variant with a different tone to express importance or category. Do not invent custom colors to dim or saturate. The variant paints the leading icon badge (and the border of a selected chip), not the body of the chip: give the chip an icon when its color has to carry meaning.

<!-- Status chips -->
<mds-chip label="Completato" icon="mi/baseline/check-circle" variant="success" tone="strong"></mds-chip>
<mds-chip label="In attesa" icon="mi/baseline/schedule" variant="warning" tone="weak"></mds-chip>
<mds-chip label="Errore" icon="mi/baseline/error" variant="error" tone="strong"></mds-chip>

<!-- Decorative label chips -->
<mds-chip label="Natura" icon="mi/baseline/eco" variant="green" tone="weak"></mds-chip>
<mds-chip label="Tecnologia" icon="mi/baseline/computer" variant="blue" tone="strong"></mds-chip>

Chip with Leading Icon

Reference icons by their filename slug (no .svg extension). The icon is rendered decoratively to the left of the label inside a circular badge.

<mds-chip
  label="Animali"
  icon="mi/baseline/pets"
  variant="primary"
  tone="strong"
></mds-chip>

Clickable Chip (Action, No Toggle)

Use clickable when the chip triggers an action but does not need a persistent selected state. The component adds role="button", focus handling, and keyboard activation. Listen for mdsChipClickLabel.

<mds-chip
  label="Apri dettagli"
  clickable
  icon="mi/baseline/open-in-new"
  variant="primary"
  tone="weak"
></mds-chip>

<script>
  document.querySelector('mds-chip').addEventListener('mdsChipClickLabel', (e) => {
    console.log('clicked', e.detail.element);
  });
</script>

Selectable Chip (Toggle)

Use selectable for filter or choice chips where the visual selected state matters. selectable implies clickable automatically. Activating the chip flips selected; the event mdsChipSelect carries the new value in e.detail.selected (true, or undefined when deselected).

<mds-chip
  label="Vegetariano"
  selectable
  icon="mi/baseline/eco"
  variant="success"
  tone="weak"
></mds-chip>

<script>
  document.querySelector('mds-chip').addEventListener('mdsChipSelect', (e) => {
    console.log('selezionato:', e.detail.selected);
  });
</script>

Pre-selected Chip

Set selected externally to initialize a selectable chip in the selected state (e.g. when restoring saved filter state). An unselected chip carries no selected attribute.

<mds-chip
  label="Urgente"
  selectable
  selected
  variant="error"
  tone="strong"
></mds-chip>

Deletable Chip (Removable Token)

Use deletable for chips the user is meant to dismiss - for example tags on an entity or active filters. A trailing cancel button emits mdsChipDelete on activation.

<mds-chip
  label="Mario Rossi"
  deletable
  icon="mi/baseline/person"
  variant="primary"
  tone="weak"
></mds-chip>

<script>
  document.querySelector('mds-chip').addEventListener('mdsChipDelete', (e) => {
    e.detail.element.remove();
  });
</script>

Fully Interactive Chip

Combine clickable (or selectable) with deletable for chips that can both be activated and removed independently.

<mds-chip
  label="Sport invernali"
  clickable
  deletable
  icon="mi/baseline/downhill-skiing"
  variant="info"
  tone="weak"
></mds-chip>

Disabled Chip

Set the disabled attribute to dim the chip, block pointer interaction and set aria-disabled="true". The styling keys on the attribute (the prop is not reflected), and keyboard activation is not blocked: a clickable label or a delete button stays focusable and Enter still fires its event. Do not use disabled="false" - remove the attribute to re-enable.

<mds-chip
  label="Non disponibile"
  disabled
  variant="dark"
  tone="strong"
></mds-chip>

Styling Customization

Style the chip only through its documented --mds-chip-* 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. Every token has a -selected twin (--mds-chip-background-selected, --mds-chip-border-selected, --mds-chip-color-selected, --mds-chip-icon-background-selected, --mds-chip-icon-color-selected, --mds-chip-shadow-selected); when selected is set the component swaps each token for its twin, so override the twin to restyle the selected state. A resting token set on the host from outside wins over that swap: scope it to :not([selected]).

.filtri-categoria mds-chip:not([selected]) {
  --mds-chip-background: rgb(var(--magma-accent-surface));
  --mds-chip-color: rgb(var(--magma-accent-fg));
}

.filtri-categoria mds-chip {
  --mds-chip-icon-background: rgb(var(--magma-accent-emphasis));
  --mds-chip-icon-color: rgb(var(--magma-accent-on-emphasis));
  --mds-chip-background-selected: rgb(var(--magma-accent-emphasis));
  --mds-chip-color-selected: rgb(var(--magma-accent-on-emphasis));
}