Vai al contenuto principale

Bootstrap Italia

Il tema Bootstrap 5 per lo sviluppo di applicazioni web per la PA
Cerca nella documentazione

Tooltip

Tooltip

Documentazione ed esempi per aggiungere tooltip personalizzati.

I tooltip sono suggerimenti personalizzati con CSS e JavaScript, utilizzano CSS3 per le animazioni e gli attributi data-bs per l’archiviazione di titoli locali.

Accessibilità

I tooltip funzionano sia con la tastiera che per gli utenti dotati di tecnologia assistiva.

È importante aggiungere tooltip solo ad elementi HTML che sono tradizionalmente attivabili da tastiera e interattivi (link, pulsanti, o elementi di form).

Sebbene arbitrariamente gli elementi HTML (come <span>) possano essere resi attivabili tramite l’attributo tabindex="0", ciò aggiungerà interruzioni di tabulazioni potenzialmente dannose per gli utenti che usano la tastiera per navigare. Inoltre, la maggior parte delle tecnologie assistive in questa situazione non annuncia il tooltip come ci si potrebbe invece attendere.

Infine, non fare affidamento esclusivamente sull’evento “mouse over” come innesco del tooltip, in quanto ciò renderà impossibile l’attivazione per gli utenti che usano la tastiera per navigare.

Cose da sapere quando usi il plugin tooltip:

  • I tooltip si basano sulla libreria di terze parti Popper.js. Per fare in modo che i tooltip funzionino è quindi necessario includere popper.min.js prima di bootstrap-italia.js o usare la versione bundle che contiene già Popper.js.
  • I tooltip sono opt-in per ragioni di performance, quindi devi inizializzarli tu stesso con il codice che trovi di seguito.
  • I tooltip con titoli vuoti non saranno mai visualizzati.
  • Specifica container: 'body' per evitare problemi di rendering in componenti più complessi (come nei gruppi di input, gruppi di pulsanti, etc).
  • Attivare i tooltip su elementi nascosti non funzionerà.
  • I tooltip per gli elementi .disabled o disabled devono essere attivati da un elemento contenitore.
  • Quando attivati da collegamenti ipertestuali che si estendono su più righe, i tooltip verranno centrati. Usa white-space: nowrap;sui tuoi <a> per evitare questo comportamento.
  • I tooltip devono essere nascosti prima che i loro elementi corrispondenti siano stati rimossi dal DOM.

Abilitazione di tooltip

Un modo per inizializzare tutti i tooltip su una pagina è quello di selezionarli tramite il loro attributo data-bs-toggle:

1
2
3
4
5
6

import { Tooltip } from 'bootstrap-italia'

const tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
const tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
  return new Tooltip(tooltipTriggerEl);
})

Altri esempi

Passa il mouse sopra i link sottostanti per visualizzare i tooltip:

Ecco un bianco scenario
per tratteggiarvi l’accompagnamento
degli oggetti di sfondo che pur vivono.
Non ne sarò l’artefice impaziente.
Berrò alle coppe della nostalgia,
avrò preteso d’ozio nelle lacrime...
perché non mi ribello alla natura:
la mia lentezza li esaspera...
La mia lentezza? No, la mia fiducia.
Per adesso è deserto.
Il mondo può rifarsi senza me,
E intanto gli altri mi denigreranno

La città nuova, Alda Merini 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

<div class="tooltip-demo">
  <p class="font-serif muted">
    Ecco un <a href="#" data-bs-toggle="tooltip" title="Primo tooltip">bianco scenario</a><br/>
    per tratteggiarvi l’accompagnamento<br/>
    degli oggetti di sfondo che pur vivono.<br/>
    Non ne sarò <a href="#" data-bs-toggle="tooltip" title="Secondo tooltip">l’artefice</a> impaziente.<br/>
    Berrò alle coppe della nostalgia,<br/>
    avrò preteso d’ozio nelle lacrime...<br/>
    perché non mi ribello alla natura:<br/>
    la mia lentezza li esaspera...<br/>
    La mia lentezza? No, la mia fiducia.<br/>
    Per adesso è deserto.<br/>
    <a href="#" data-bs-toggle="tooltip" title="Terzo tooltip">Il mondo può rifarsi senza me</a>,<br/>
    E intanto gli altri mi denigreranno
  </p>
  <small>
    <em>La città nuova, Alda Merini</em>
  </small>
</div>

Passa il mouse sopra i pulsanti sottostanti per vedere le quattro direzioni dei tooltip: sopra, destra, sotto, e sinistra.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

<div class="tooltip-demo">
  <div class="bd-example-tooltips">
    <div class="container">
      <div class="row mt-3">
        <div class="col-6">
          <button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="top" title="Tooltip in alto" style="width: 100%;">Tooltip in alto</button>
        </div>
        <div class="col-6">
          <button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="bottom" title="Tooltip on bottom" style="width: 100%;">Tooltip in basso</button>
        </div>
      </div>
      <div class="row mt-5">
        <div class="col-5"></div>
        <div class="col-6">
          <button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="left" title="Tooltip a sinistra" style="width: 100%;">Tooltip a sinistra</button>
        </div>
        <div class="col-1"></div>
      </div>
      <div class="row mt-5">
        <div class="col-1"></div>
        <div class="col-6">
          <button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="right" title="Tooltip a destra" style="width: 100%;">Tooltip a destra</button>
        </div>
        <div class="col-5"></div>
      </div>
      <div class="row mt-5">
        <div class="col-3"></div>
        <div class="col-6">
          <button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-html="true" title="<em>Tooltip</em> <u>con</u> <strong>HTML</strong>" style="width: 100%;">Tooltip con HTML</button>
        </div>
        <div class="col-3"></div>
      </div>
    </div>
  </div>
</div>

E con codice HTML personalizzato:

1
2
3

<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-html="true" title="<em>Tooltip</em> <u>con</u> <strong>HTML</strong>">
  Tooltip con HTML
</button>

Attivazione tramite codice

Nel caso in cui si desidera che il componente sia inizializzato in maniera automatica utilizzare l’attributo data-bs-toggle specifico per la sua inizializzazione automatica.

Nel caso in cui si desidera importare e inizializzare autonomamente il componente l’attributo data-bs-toggle specifico non deve essere incluso così da evitare inizializzazioni automatiche che possono portare a comportamenti inaspettati.

Per maggiori informazioni consulta la sezione JavaScript di Bootstrap Italia.

Il plugin del tooltip genera contenuto e markup su richiesta, e in modo predefinito posiziona i tooltip dopo i loro elementi attivati.

Tramite data attributes

Di seguito è mostrato un esempio che esplicita il funzionamento interno di Bootstrap per la gestione di Tooltip.

Il markup richiesto per un tooltip è costituito da un attributo data-bs- e title sull’elemento HTML sul quale si vuole abilitare un tooltip. Ad esempio, quando nella pagina è scritto questo codice HTML:

1

<a href="#" data-bs-toggle="tooltip" title="Testo di esempio del tooltip">Link che attiva il tooltip</a>

Nel momento in cui tale elemento riceve focus da tastiera (o c’è un evento hover), Bootstrap genera il markup seguente:

1
2
3
4
5
6

<a href="#" data-bs-toggle="tooltip" title="Testo di esempio del tooltip!" aria-describedby="tooltip0123456">Link che attiva il tooltip</a>

<div class="tooltip bs-tooltip-top" role="tooltip" id="tooltip0123456">
  <div class="tooltip-arrow"></div>
  <div class="tooltip-inner">Testo di esempio del tooltip</div>
</div>

Tramite JavaScript

È possibile attivare un tooltip tramite JavaScript:

1
2
3
4
5

import { Tooltip } from 'bootstrap-italia';

document.querySelectorAll('.tooltipEl').forEach(el => {
  new Tooltip(el);
});

Opzioni

Le opzioni possono essere passate tramite attributi data o tramite JavaScript. Per gli attributi data, aggiungi l’opzione nome a data-bs-, come in data-bs-animation="".

Nome Tipo Predefinito Descrizione
allowList oggetto Valore predefinito Oggetto che contiene attributi e tag consentiti.
animazione booleano vero Applica una transizione di dissolvenza CSS al tooltip.
boundary string, element 'clippingParents' Limite del vincolo di overflow del tooltip (si applica solo al modificatore preventOverflow di Popper). Per impostazione predefinita, è 'clippingParents' e può accettare un riferimento HTMLElement (solo tramite JavaScript). Per maggiori informazioni, consulta la documentazione di Popper su detectOverflow.
contenitore stringa, elemento, false false Aggiunge il suggerimento a un elemento specifico. Esempio: contenitore: 'corpo'. Questa opzione è particolarmente utile in quanto consente di posizionare il tooltip nel flusso del documento vicino all'elemento di attivazione, il che impedirà al tooltip di allontanarsi dall'elemento di attivazione durante il ridimensionamento di una finestra.
customClass stringa, funzione '' Aggiungi classi al tooltip quando viene visualizzato. Nota che queste classi verranno aggiunte in aggiunta a tutte le classi specificate nel modello. Per aggiungere più classi, separale con spazi: 'class-1 class-2'. Puoi anche passare una funzione che dovrebbe restituire una singola stringa contenente nomi di classi aggiuntivi.
delay number, object 0 Ritardo nella visualizzazione e nell'occultamento del tooltip (ms): non si applica al tipo di trigger manuale. Se viene fornito un numero, il ritardo viene applicato sia a hide/show. La struttura dell'oggetto è: delay: { "show": 500, "hide": 100 }.
fallbackPlacements array ['top', 'right', 'bottom', 'left'] Definisci i posizionamenti di fallback fornendo un elenco di posizionamenti nell'array (in ordine di preferenza). Per maggiori informazioni, consulta la documentazione sul comportamento di Popper.
html booleano false Consenti HTML nella descrizione comando. Se è vero, i tag HTML nel titolo della descrizione comando verranno renderizzati nella descrizione comando. Se è falso, verrà utilizzata la proprietà innerText per inserire contenuto nel DOM. Usa il testo se sei preoccupato per gli attacchi XSS.
offset array, stringa, funzione [0, 0] Offset del tooltip rispetto al suo target. Puoi passare una stringa negli attributi dati con valori separati da virgole come: data-bs-offset="10,20". Quando una funzione viene utilizzata per determinare l'offset, viene chiamata con un oggetto contenente il posizionamento del popper, il riferimento e i rettangoli del popper come primo argomento. Il nodo DOM dell'elemento di attivazione viene passato come secondo argomento. La funzione deve restituire un array con due numeri: skidding, distance. Per maggiori informazioni, consulta la documentazione offset di Popper.
placement string, function 'top' Come posizionare il tooltip: auto, top, bottom, left, right. Quando viene specificato auto, il tooltip verrà riorientato dinamicamente. Quando una funzione viene utilizzata per determinare il posizionamento, viene chiamata con il nodo DOM tooltip come primo argomento e il nodo DOM elemento di attivazione come secondo. Il contesto this è impostato sull'istanza tooltip.
popperConfig null, object, function null Per modificare la configurazione Popper predefinita di Bootstrap, vedere Configurazione di Popper. Quando una funzione viene utilizzata per creare la configurazione Popper, viene chiamata con un oggetto che contiene la configurazione Popper predefinita di Bootstrap. Ti aiuta a utilizzare e unire la configurazione predefinita con la tua. La funzione deve restituire un oggetto di configurazione per Popper.
sanitize boolean true Abilita o disabilita la sanificazione. Se attivate, le opzioni 'template', 'content' e 'title' verranno sanificate.
sanitizeFn null, function null Qui puoi specificare la tua funzione di sanificazione. Può essere utile se preferisci usare una libreria dedicata per eseguire la sanificazione.
selector string, false false Se viene fornito un selettore, gli oggetti tooltip saranno delegati ai target specificati. In pratica, questo viene usato anche per applicare tooltip agli elementi DOM aggiunti dinamicamente (supporto jQuery.on). Guarda questo problema e un esempio informativo. Nota: l'attributo title non deve essere utilizzato come selettore.
template string '<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>' HTML di base da utilizzare durante la creazione del tooltip. Il title del tooltip verrà inserito in .tooltip-inner. .tooltip-arrow diventerà la freccia del tooltip. L'elemento wrapper più esterno dovrebbe avere la classe .tooltip e role="tooltip".
title stringa, elemento, funzione '' Valore predefinito del titolo se l'attributo title non è presente. Se viene fornita una funzione, verrà chiamata con il suo riferimento this impostato sull'elemento a cui è collegato il popover.
trigger stringa 'hover focus' Come viene attivato il tooltip: clic, passaggio del mouse, focus, manuale. Puoi passare più trigger; separali con uno spazio. 'manual' indica che il tooltip verrà attivato a livello di programmazione tramite i metodi .tooltip('show'), .tooltip('hide') e .tooltip('toggle'); questo valore non può essere combinato con nessun altro trigger. 'hover' da solo genererà tooltip che non possono essere attivati ​​tramite la tastiera e dovrebbe essere utilizzato solo se sono presenti metodi alternativi per trasmettere le stesse informazioni agli utenti della tastiera.

Metodi

Metodi asincroni e transizioni

Tutti i metodi API sono asincroni e avviano una transizione. Ritornano al chiamante non appena viene avviata la transizione ma prima che termini. Inoltre, una chiamata al metodo su un componente in transizione verrà ignorata.

Per maggiori informazioni consulta la documentazione Javascript di Bootstrap (in inglese).

Metodo Descrizione
getInstance Metodo statico che consente di ottenere l'istanza di avviso associata a un elemento DOM, è possibile utilizzarlo in questo modo: Tooltip.getInstance(domElement).
getOrCreateInstance Metodo statico che restituisce un'istanza di avviso associata a un elemento DOM o ne crea una nuova nel caso in cui non fosse stata inizializzata. Puoi utilizzarla in questo modo: Tooltip.getOrCreateInstance(element).
dispose Rimuove la funzionalità Tooltip.
show Mostra il tootlip di un elemento. Ritorna al chiamante prima che il tooltip sia stato effettivamente mostrato (i.e. prima che si verifichi l'evento "shown.bs.tooltip"). Questo è considerato un'attivazione "manuale" del tooltip. I tooltip senza titoli non vengono mai visualizzati.
hide Nascondi il tootltip di un elemento. Ritorna al chiamante prima che il tooltip sia stato effettivamente nascosto (i.e. prima che si verifichi l'evento "hidden.bs.tooltip"). Questo è considerato un'attivazione "manuale" del tooltip.
toggle Attiva/Disattiva il tooltip di un elemento. Ritorna al chiamante prima che il tooltip sia stato effettivamente mostrato o nascosto (i.e. prima che si verifichi l'evento "shown.bs.tooltip" o l'evento "hidden.bs.tooltip"). Questo è considerato un'attivazione "manuale" del tooltip.
enable Fornisce al tooltip di un elemento la possibilità di essere mostrato. I tooltip sono abilitati in modo predefinito.
disable Rimuove la capacità di mostrare il tooltip di un elemento. Il tooltip potrà essere mostrato solo se è riattivato.
toggleEnabled Attiva/disattiva la possibilità che il tooltip di un elemento sia mostrato o nascosto.
update Aggiorna la posizione del tooltip di un elemento.

Eventi

Tipo di evento Descrizione
show.bs.tooltip Questo evento si attiva immediatamente quando viene chiamato il metodo show.
shown.bs.tooltip Questo evento viene attivato quando il tooltip è stato reso visibile all'utente (attenderà il completamento delle transizioni CSS).
hide.bs.tooltip Questo evento si attiva immediatamente quando viene chiamato il metodo hide.
hidden.bs.tooltip Questo evento viene generato quando il tooltip ha finito di essere nascosto all'utente (attenderà il completamento delle transizioni CSS).
inserted.bs.tooltip Questo evento si attiva dopo l'evento show.bs.tooltip quando il modello del tooltip è stato aggiunto al DOM.