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

Basic Tooltip on a Button

The most common form. Give the trigger element an id (or any unique CSS selector) and point target at it. The tooltip listens for hover events on the trigger and positions itself automatically.

<mds-button id="salva-btn" label="Salva documento" variant="primary" tone="strong"></mds-button>
<mds-tooltip target="#salva-btn">Salva le modifiche correnti</mds-tooltip>

Naming an Icon-Only Button

On an icon-only button the tooltip usually shows the name of the button. Set relation="label" so that the tooltip is the name (aria-labelledby) and not a description: the button needs no aria-label, and a screen reader does not read the same text twice. Use it only on an interactive trigger, a button or a link: ARIA does not allow a name on a generic element.

<mds-button id="tokens-btn" icon="mi/baseline/palette" variant="dark" tone="text"></mds-button>
<mds-tooltip target="#tokens-btn" relation="label">Tokens</mds-tooltip>

Tooltip on a Non-Interactive Element

target accepts any CSS selector, not just #id. Use a class or attribute selector when the trigger is a static element such as a status icon.

<mds-icon class="stato-icona" name="mi/baseline/info"></mds-icon>
<mds-tooltip target=".stato-icona">Ultima sincronizzazione: oggi alle 08:30</mds-tooltip>

Placement and Preferred Side

Override the default top placement with placement when layout requires a different side. Auto placement is on by default and picks the side by itself, so placement takes effect only together with disable-auto-placement, which locks the side.

<mds-button id="dettagli-btn" label="Dettagli" variant="primary" tone="outline"></mds-button>
<mds-tooltip target="#dettagli-btn" placement="right" disable-auto-placement>
  Apre il pannello laterale con i dettagli completi
</mds-tooltip>

Accepted values: top, top-start, top-end, bottom, bottom-start, bottom-end, left, left-start, left-end, right, right-start, right-end.

Flip Fallback When Space is Tight

Enable flip so the tooltip moves to the opposite side if the preferred placement collides with the viewport edge. It works only together with disable-auto-placement: it keeps a preferred side while allowing a single-axis fallback.

<mds-button id="azione-btn" label="Azione" variant="primary"></mds-button>
<mds-tooltip target="#azione-btn" placement="top" disable-auto-placement flip>
  Esegui l'operazione selezionata
</mds-tooltip>

Viewport-Safe Shift

By default the tooltip slides along its axis so it stays inside the viewport (set disable-shift to opt out). Increase shift-padding to keep a wider safe margin from the viewport edges.

<mds-button id="bordo-btn" label="Vicino al bordo" variant="dark" tone="outline"></mds-button>
<mds-tooltip target="#bordo-btn" shift-padding="24">
  Questa azione e' irreversibile
</mds-tooltip>

Custom Offset Distance

Increase offset when additional breathing room between the trigger and the bubble is required - for example inside dense toolbars or on elements with large focus rings.

<mds-button id="info-btn" label="Info" variant="info" tone="weak"></mds-button>
<mds-tooltip target="#info-btn" offset="20">
  Informazioni aggiuntive sul campo
</mds-tooltip>

Programmatic Visibility

Set the visible attribute (or property) to control the tooltip without hover. Useful for guided tours, onboarding hints, or error annotations that appear on demand.

<mds-button id="primo-accesso" label="Inizia" variant="primary"></mds-button>
<mds-tooltip id="hint" target="#primo-accesso" visible>
  Benvenuto! Clicca qui per iniziare la configurazione.
</mds-tooltip>

<script>
  const hint = document.querySelector('#hint');
  // Dismiss programmatically when the user acknowledges the hint
  document.querySelector('#primo-accesso').addEventListener('click', () => {
    hint.visible = false;
  });
</script>

Typography Scale

typography adjusts the text scale inside the bubble. Use 'tip' (default) for compact hints, 'caption' for slightly larger labels, and 'detail' for the largest, body-size text.

<!-- Default compact hint -->
<mds-tooltip target="#campo-nome" typography="tip">Massimo 64 caratteri</mds-tooltip>

<!-- Slightly larger label -->
<mds-tooltip target="#campo-data" typography="caption">Formato: GG/MM/AAAA</mds-tooltip>

Positioning Strategy

Use strategy="absolute" when the tooltip must be contained within a scrolling ancestor instead of the viewport. The default strategy="fixed" escapes any clipping or overflow-hidden parent.

<!-- Inside a scrollable panel with overflow:hidden ancestors -->
<mds-tooltip target="#voce-lista" strategy="absolute">Trascina per riordinare</mds-tooltip>

Styling Customization

Style the tooltip only through its documented --mds-tooltip-* CSS custom properties. Set them on the host element or a parent selector; use the semantic color roles via rgb(var(--magma-<role>)) so dark mode and high-contrast modes keep working.

.onboarding-hint mds-tooltip {
  --mds-tooltip-background: rgb(var(--magma-accent-surface));
  --mds-tooltip-arrow-background: rgb(var(--magma-accent-surface));
  --mds-tooltip-delay: 0.25s;
  --mds-tooltip-duration: 0.3s;
  --mds-tooltip-z-index: 5000;
}