@pzeta/vue-components
Feedback

Tooltip

Testo contestuale che appare al hover/focus su un elemento. Disponibile come componente Vue e come direttiva v-tooltip per uso diretto su qualsiasi elemento HTML.

Import

// Componente
import { Tooltip } from '@pzeta/vue-components'

// Direttiva
import { vTooltip } from '@pzeta/vue-components'

// Oppure tramite plugin (registra entrambi):
import { FeedbackPlugin } from '@pzeta/vue-components'
app.use(FeedbackPlugin)

Utilizzo come componente

Il componente <Tooltip> wrappa l'elemento target nello slot default e mostra il tooltip al suo interno.

Utilizzo come direttiva v-tooltip

La direttiva v-tooltip si applica direttamente a qualsiasi elemento HTML senza wrapper.

Props del componente Tooltip

PropTipoDefaultDescrizione
contentstring—Testo del tooltip
position'top' | 'bottom' | 'left' | 'right''top'Posizione rispetto all'elemento target
trigger'hover' | 'focus' | 'click''hover'Evento che attiva il tooltip
disabledbooleanfalseDisabilita il tooltip
idstring—ID personalizzato (default: generato automaticamente)
classstring—Classe CSS aggiuntiva per il box del tooltip
showDelaynumber0Ritardo in ms prima di mostrare il tooltip
hideDelaynumber0Ritardo in ms prima di nascondere il tooltip
autoHidebooleantrueNasconde automaticamente al mouse leave
escapebooleantrueSe true fa escape dell'HTML; se false interpreta HTML (sanitizzato)
fitContentbooleantrueAdatta la larghezza al contenuto
zIndexnumber1100Z-index del tooltip

Emits del componente Tooltip

EventoPayloadDescrizione
show—Emesso quando il tooltip diventa visibile
hide—Emesso quando il tooltip viene nascosto

Slot del componente Tooltip

SlotScopeDescrizione
default—Elemento target su cui il tooltip è ancorato
content—Contenuto custom del tooltip (sostituisce la prop content)

Opzioni della direttiva v-tooltip

OpzioneTipoDefaultDescrizione
valuestring—Testo da mostrare
position'top' | 'bottom' | 'left' | 'right''top'Posizione del tooltip
showDelaynumber0Ritardo in ms prima di mostrare
hideDelaynumber0Ritardo in ms prima di nascondere
disabledbooleanfalseDisabilita il tooltip
escapebooleantrueEscape HTML nel contenuto
tooltipClassstring—Classi CSS aggiuntive
zIndexnumber9999Z-index del tooltip

Esempi

Componente: posizioni

Componente: trigger click

Componente: contenuto HTML via slot

Componente: con delay

Direttiva: configurazione avanzata

Direttiva: disabilitazione condizionale

Direttiva: pulsante disabilitato

Il caso tipico è spiegare perché un pulsante è disabilitato. Un elemento disabled non riceve eventi del puntatore (e i pulsanti della libreria hanno anche pointer-events: none), quindi la direttiva rileva il passaggio del mouse sul contenitore e lo confronta con il rettangolo dell'elemento. Vale per disabled e per aria-disabled="true", e lo stato viene letto al momento: un pulsante che si abilita o disabilita dopo il mount non richiede altro.

<div class="flex gap-2">
  <Button
    v-tooltip="'Compila prima il cliente'"
    label="Salva"
    :disabled="!clienteCompilato"
  />
</div>

Da tastiera un pulsante disabled non riceve il focus, quindi il tooltip non può comparire: il motivo va reso disponibile anche in un testo visibile (es. un messaggio sotto il form), oppure usare aria-disabled="true" al posto di disabled gestendo il blocco del click nell'handler.

Registrazione manuale della direttiva

// main.ts
import { createApp } from 'vue'
import { vTooltip } from '@pzeta/vue-components'
import App from './App.vue'

const app = createApp(App)
app.directive('tooltip', vTooltip)
app.mount('#app')

Accessibilità

  • Il componente usa aria-describedby sull'elemento target con l'ID del tooltip.
  • Il tooltip ha role="tooltip".
  • La direttiva aggiunge role="tooltip" al nodo DOM creato.
  • Il tooltip si chiude con il tasto Escape.
  • Si attiva anche con focus per supporto navigazione da tastiera.
  • Sugli elementi disabilitati compare al passaggio del mouse ma non da tastiera (un disabled non riceve il focus): vedi Direttiva: pulsante disabilitato.

Metodi esposti (componente)

const tooltipRef = ref()

// Controllo programmatico
tooltipRef.value.show()    // Mostra
tooltipRef.value.hide()    // Nasconde
tooltipRef.value.toggle()  // Toggle

TypeScript

import type { TooltipProps, TooltipEmits, TooltipSlots } from '@pzeta/vue-components'
import type { TooltipPosition, TooltipTrigger } from '@pzeta/vue-components'
import { vTooltip } from '@pzeta/vue-components'

// TooltipPosition = 'top' | 'bottom' | 'left' | 'right'
// TooltipTrigger  = 'hover' | 'focus' | 'click'

Toast

Sistema di notifiche temporanee posizionate sullo schermo. Si usa tramite il composable useToast() per mostrare messaggi da qualsiasi componente.

Feedback

Componenti di feedback visivo — Badge, Tag, Chip, Avatar, Message, Toast, ProgressBar, ProgressSpinner, Skeleton, Tooltip, EmptyState.