Popover

Documentazione ed esempi per aggiungere popover (tooltip informativi) a qualsiasi elemento del tuo sito.

I popover si basano sulla libreria di terze parti Popper.js. Per fare in modo che i popover funzionino è necessario includere popper.min.js prima di bootstrap-italia.js o usare la versione bundle che contiene già Popper.js. I popovers richiedono il plugin tooltip come dipendenza.

Accessibilità

I popover funzionano sia con la tastiera che per gli utenti dotati di tecnologia assistiva. Allo stesso modo di quanto avviene per i Tooltip, il codice generato per i Popover è accessibile.

Cose da sapere quando si utilizza il plugin popover:

I popover sono opt-in per ragioni di performance, quindi devi inizializzarli tu stesso con il codice che trovi di seguito.
I title e i content con valori vuoti non mostreranno mai popover.
Specifica container: 'body' per evitare problemi di rendering in componenti più complessi (come nei gruppi di input, gruppi di pulsanti, etc).
Attivare i popover su elementi nascosti non funzionerà.
I popover per gli elementi .disabled o disabled devono essere attivati da un elemento contenitore.
Quanto attivato da ancore che si estendono su più linee, i popover verranno centrati tra la larghezza complessiva delle ancore. Usa white-space: nowrap; sugli elementi <a> per evitare questo comportamento.
I Popover devono essere nascosti prima che i loro elementi corrispondenti siano stati rimossi dal DOM.

Attivazione generale

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

var popoverTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="popover"]'))
var popoverList = popoverTriggerList.map(function (popoverTriggerEl) {
  return new bootstrap.Popover(popoverTriggerEl)
})

Attivazione con opzione container

Quando hai alcuni stili su un elemento genitore che interferiscono con un popover, è consigliato specificare un container personalizzato in modo che l’HTML del popover appaia invece all’interno di quell’elemento.

var popover = new bootstrap.Popover(document.querySelector('.example-popover'), {
  container: 'body',
})

1
<button type="button" class="btn btn-lg btn-danger fade show" data-bs-toggle="popover" title="Titolo del Popover" data-bs-content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc vel finibus augue.">Clicca per attivare/disattivare il popover</button>

Esempi

Posizione

Sono disponibili quattro opzioni: allineato in alto, a destra, in basso e a 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
<div class="container">
  <div class="row">
    <div class="col-12 col-md-4"></div>
    <div class="col-12 col-md-4">
      <button type="button" class="btn btn-secondary fade show" data-container="body" data-bs-toggle="popover" data-bs-placement="top" title="Titolo del Popover" data-bs-content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc vel finibus augue." style="width:100%;">
        Popover in alto
      </button>
    </div>
    <div class="col-12 col-md-4"></div>
  </div>
  <div class="row mt-4">
    <div class="col-12 col-md-4">
      <button type="button" class="btn btn-secondary fade show" data-container="body" data-bs-toggle="popover" data-bs-placement="right" title="Titolo del Popover" data-bs-content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc vel finibus augue." style="width:100%;">
        Popover a destra
      </button>
    </div>
    <div class="col-12 col-md-4"></div>
    <div class="col-12 col-md-4 mt-4 mt-md-0">
      <button type="button" class="btn btn-secondary fade show" data-container="body" data-bs-toggle="popover" data-bs-placement="left" title="Titolo del Popover" data-bs-content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc vel finibus augue." style="width:100%;">
        Popover a sinistra
      </button>
    </div>
  </div>
  <div class="row mt-4">
    <div class="col-12 col-md-4"></div>
    <div class="col-12 col-md-4">
      <button type="button" class="btn btn-secondary fade show" data-container="body" data-bs-toggle="popover" data-bs-placement="bottom" title="Titolo del Popover" data-bs-content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc vel finibus augue." style="width:100%;">
        Popover in basso
      </button>
    </div>
    <div class="col-12 col-md-4"></div>
  </div>
</div>

Titolo con icona e link

È possibile aggiungere un’icona in testa al titolo ed un link in coda al contenuto. In questo casi è necessario aggiungere l’attributo data-bs-html="true" al pulsante che apre il Popover e disabilitare la funzione di sanitize attraverso l’opzione { sanitize: false }.

L’icona va inclusa come HTML nell’attributo title="" subito prima del vero e proprio titolo.

Il link come HTML nell’attributo data-bs-content="" dopo il contenuto testuale, con classe .popover-inner-link.

1
2
3
<button type="button" class="btn btn-secondary fade show" data-container="body" data-bs-toggle="popover" data-bs-placement="top" data-bs-html="true" title="<svg class='icon'><use href='/dist/svg/sprites.svg#it-help-circle'></use></svg> Titolo con icona" data-bs-content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc vel finibus augue.<a href='#' class='popover-inner-link'>Leggi tutto<svg class='icon'><use href='/dist/svg/sprites.svg#it-arrow-right'></use></svg></a>">
Popover con icona e link
</button>

Prestare attenzione alla inizializzazione del Popover contenente le icone come nel caso sopra: per la corretta visualizzazione del componente occorre disabilitare l’opzione di sanitize.

var popover = new bootstrap.Popover(document.querySelector('.example-popover'), {
  sanitize: false,
})

Modalità Hover

Per aprire il Popover all’hover del mouse sull’elemento, aggiungere l’attributo data-bs-trigger="hover" al tag dello stesso.

1
2
3
<button type="button" class="btn btn-secondary fade show" data-container="body" data-bs-toggle="popover" data-bs-trigger="hover" data-bs-placement="right" data-html="true" title="Popover in Hover" data-bs-content="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc vel finibus augue.">
Apertura in Hover
</button>

Chiusura al click successivo

Usa l’evento focus per ignorare i popover sul clic successivo dell’utente di un elemento diverso rispetto all’elemento di attivazione / disattivazione.

Markup specifico richiesto per ignorare il click successivo

Per il giusto comportamento cross-browser e cross-platform, è necessario utilizzare il tag <a>, non il tag <button>, ed è necessario anche includere l’attributo tabindex.

Popover richiudibile

1
<a tabindex="0" href="#" class="btn btn-lg btn-danger fade show" role="button" data-bs-toggle="popover" data-bs-trigger="focus" title="Popover richiudibile" data-bs-content="Ecco il contenuto del popover richiudibile">Popover richiudibile</a>

var popover = new bootstrap.Popover(document.querySelector('.popover-dismiss'), {
  trigger: 'focus',
})

Elementi disabilitati

Elementi con l’attributo disabled non sono interattivi, il che significa che gli utenti non possono attivare il popover (o un tooltip) con il passaggio del mouse o facendo click su di essi. Come soluzione, ti consigliamo di attivare il popover da un elemento <div> o <span> contenitore e sovrascrivere il pointer-events su un elemento disabilitato.

Per gli eventi dei popover disabilitati, potresti preferire data-bs-trigger="hover" in modo che il popover appaia come feedback visivo immediato per gli utenti in quanto non possono aspettarsi di cliccare su un elemento disabilitato.

1
2
3
<span class="d-inline-block fade show" data-bs-toggle="popover" data-bs-content="Popover disabilitato">
<button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Popover disabilitato</button>
</span>

Attivazione tramite codice

Nel caso in cui si desidera che i componenti siano inizializzati in maniera automatica (salvo casi particolari) utilizzare l’attributo data-bs-toggle specifico per l’inizializzazione automatica del componente.

Nel caso in cui si desidera importare e inizializzare autonomamente i singoli componenti, l’attributo data-bs-toggle specifico non deve essere incluso, per evitare inizializzazioni automatiche che possono portare a comportamenti inaspettati.

Per maggiori informazioni consulta la sezione JavaScript di Bootstrap Italia.

Abilita i popover tramite JavaScript:

import { Popover } from 'bootstrap-italia';

const exampleEl = document.getElementById('example');
const popover = new Popover(exampleEl, options);

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 popover.
`boundary`	string, element	`'clippingParents'`	Limite di vincolo di overflow del popover (si applica solo al modificatore preventOverflow di Popper). Per impostazione predefinita, è `'clippingParents'` e può accettare un riferimento HTMLElement (solo tramite JavaScript). Per maggiori informazioni, fare riferimento alla documentazione detectOverflow di Popper.
`contenitore`	stringa, elemento, false	`false`	Aggiunge il popover a un elemento specifico. Esempio: `contenitore: 'corpo'`. Questa opzione è particolarmente utile in quanto consente di posizionare il popover nel flusso del documento vicino all'elemento di attivazione, il che impedirà al popover di allontanarsi dall'elemento di attivazione durante il ridimensionamento della finestra.
`content`	stringa, elemento, funzione	`''`	Valore del contenuto predefinito se l'attributo `data-bs-content` non è presente. Se viene specificata una funzione, verrà chiamata con il suo riferimento `this` impostato sull'elemento a cui è collegato il popover.
`customClass`	stringa, funzione	`''`	Aggiungi classi al popover quando viene visualizzato. Nota che queste classi saranno aggiunte in aggiunta a qualsiasi classe specificata 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 popover (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`	string, array	`['top', 'right', 'bottom', 'left']`	Definisci i posizionamenti di fallback fornendo un elenco di posizionamenti in array (in ordine di preferenza). Per maggiori informazioni, fare riferimento alla documentazione sul comportamento di Popper.
`html`	booleano	`false`	Consenti HTML nel popover. Se è vero, i tag HTML nel `title` del popover verranno renderizzati nel popover. Se è falso, verrà utilizzata la proprietà `innerText` per inserire il contenuto nel DOM. Usa text se sei preoccupato per gli attacchi XSS.
`offset`	numero, stringa, funzione	`[0, 0]`	Offset del popover 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, fare riferimento a offset docs.
`posizionamento`	stringa, funzione	`'top'`	Come posizionare il popover: auto, top, bottom, left, right. Quando viene specificato `auto`, riorienterà dinamicamente il popover. Quando viene utilizzata una funzione per determinare il posizionamento, viene chiamata con il nodo DOM del popover come primo argomento e il nodo DOM dell'elemento di attivazione come secondo. Il contesto `this` è impostato sull'istanza del popover.
`popperConfig`	null, oggetto, 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 configurazione. 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 fornire la tua funzione di sanificazione. Ciò può essere utile se preferisci utilizzare una libreria dedicata per eseguire la sanificazione.
`selector`	string, false	`false`	Se viene fornito un selettore, gli oggetti popover verranno delegati ai target specificati. In pratica, questo viene utilizzato anche per applicare popover agli elementi DOM aggiunti dinamicamente (supporto `jQuery.on`). Vedere questo problema e un esempio informativo. Nota: l'attributo `title` non deve essere utilizzato come selettore.
`template`	string	`'<div class="popover" role="popover"><div class="popover-arrow"></div><div class="popover-inner"></div></div>'`	HTML di base da utilizzare durante la creazione del popover. Il `title` del popover verrà iniettato in `.popover-inner`. `.popover-arrow` diventerà la freccia del popover. L'elemento wrapper più esterno dovrebbe avere la classe `.popover` e `role="popover"`.
`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 popover: clic, hover, focus, manuale. Puoi passare più trigger; separali con uno spazio. `'manual'` indica che il popover verrà attivato a livello di programmazione tramite i metodi `.popover('show')`, `.popover('hide')` e `.popover('toggle')`; questo valore non può essere combinato con nessun altro trigger. `'hover'` da solo genererà popover 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: Popover.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: Popover.getOrCreateInstance(element).
dispose	Rimuove la funzionalità Popover.
`disable`	Rimuove la possibilità di mostrare il popover di un elemento. Il popover potrà essere mostrato solo se viene riattivato.
`enable`	Conferisce al popover di un elemento la possibilità di essere visualizzato. I popover sono abilitati per impostazione predefinita.
`hide`	Nasconde il popover di un elemento. Torna al chiamante prima che il popover sia stato effettivamente nascosto (ad esempio prima che si verifichi l'evento `hidden.bs.popover`). Questo è considerato un trigger "manuale" del popover.
`setContent`	Fornisce un modo per modificare il contenuto del popover dopo la sua inizializzazione.
`show`	Rivela il popover di un elemento. Ritorna al chiamante prima che il popover sia stato effettivamente mostrato (ad esempio prima che si verifichi l'evento `shown.bs.popover`). Questo è considerato un trigger "manuale" del popover. I popover il cui titolo e contenuto sono entrambi di lunghezza zero non vengono mai visualizzati.
`toggle`	Attiva/disattiva il popover di un elemento. Ritorna al chiamante prima che il popover sia stato effettivamente mostrato o nascosto (ad esempio prima che si verifichi l'evento `shown.bs.popover` o `hidden.bs.popover`). Questo è considerato un'attivazione "manuale" del popover.
`toggleEnabled`	Attiva o disattiva la possibilità che il popover di un elemento venga mostrato o nascosto.
`update`	Aggiorna la posizione del popover di un elemento.

Eventi

const myPopoverTrigger = document.getElementById('myPopover')
myPopoverTrigger.addEventListener('hidden.bs.popover', function () {
  // do something...
})

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