ComposantsJavaScript requis

Popovers

Un popover est une petite fenêtre flottante, avec titre et contenu, qui s’ouvre au clic sur un élément. Il convient à une aide un peu plus riche qu’une infobulle, sans quitter la page.

Initialisation#

Les popovers ne s’activent pas seuls : initialisez-les après le chargement de la page. Le site de cette documentation le fait déjà pour les aperçus.

const declencheurs = document.querySelectorAll('[data-bs-toggle="popover"]');
declencheurs.forEach((element) => new bootstrap.Popover(element));

Exemple de base#

Le titre vient de data-bs-title (ou title) et le contenu de data-bs-content. Un clic sur le déclencheur ouvre le popover, un second clic le ferme.

<button type="button" class="btn btn-primary" data-bs-toggle="popover" data-bs-title="Frais de virement" data-bs-content="Les virements entre comptes BDU CI sont gratuits. Vers une autre banque : 500 FCFA.">Voir les frais</button>

Positions#

data-bs-placement accepte top, right (valeur par défaut), bottom et left. Si la place manque, le popover bascule de l’autre côté.

<div class="d-flex flex-wrap gap-2">
  <button type="button" class="btn btn-secondary" data-bs-toggle="popover" data-bs-placement="top" data-bs-title="En haut" data-bs-content="Contenu du popover placé au-dessus.">Haut</button>
  <button type="button" class="btn btn-secondary" data-bs-toggle="popover" data-bs-placement="right" data-bs-title="À droite" data-bs-content="Contenu du popover placé à droite.">Droite</button>
  <button type="button" class="btn btn-secondary" data-bs-toggle="popover" data-bs-placement="bottom" data-bs-title="En bas" data-bs-content="Contenu du popover placé en dessous.">Bas</button>
  <button type="button" class="btn btn-secondary" data-bs-toggle="popover" data-bs-placement="left" data-bs-title="À gauche" data-bs-content="Contenu du popover placé à gauche.">Gauche</button>
</div>

Fermeture au clic suivant#

Avec data-bs-trigger="focus", le popover se ferme dès que l’utilisateur clique ailleurs. Utilisez un <a> avec tabindex="0" et role="button" : certains navigateurs (Safari) ne donnent pas le focus à un <button> au clic.

Plafond de carte

<a tabindex="0" class="btn btn-outline-primary" role="button" data-bs-toggle="popover" data-bs-trigger="focus" data-bs-title="Plafond de carte" data-bs-content="Le plafond mensuel de paiement est de 2 000 000 FCFA.">Plafond de carte</a>

Éléments désactivés#

Un élément désactivé ne reçoit aucun événement. Placez le popover sur un conteneur focalisable.

<span class="d-inline-block" tabindex="0" data-bs-toggle="popover" data-bs-trigger="hover focus" data-bs-content="Ce service sera disponible après la validation de votre identité.">
  <button class="btn btn-primary" type="button" disabled style="pointer-events: none;">Ouvrir un compte</button>
</span>

Contenu HTML#

Avec data-bs-html="true", titre et contenu acceptent du HTML simple (nettoyé pour des raisons de sécurité). Les liens et boutons restent utilisables au clavier tant que le popover est ouvert.

<button type="button" class="btn btn-primary" data-bs-toggle="popover" data-bs-html="true" data-bs-title="Besoin d'aide ?" data-bs-content="Appelez le &lt;strong&gt;27 20 00 00 00&lt;/strong&gt; ou rendez-vous &lt;a href='#'&gt;en agence&lt;/a&gt;.">Contacter la banque</button>

Options passées en JavaScript#

Les options peuvent être fournies à la création, y compris sous forme de fonctions. Elles priment sur les attributs data-bs-*.

const popover = new bootstrap.Popover('#bouton-aide', {
  title: 'Besoin d\'aide ?',
  content: () => document.getElementById('modele-aide').innerHTML,
  html: true,
  placement: 'bottom',
  trigger: 'focus',
  customClass: 'popover-bdu',
});

popover.show();
popover.setContent({
  '.popover-header': 'Nouveau titre',
  '.popover-body': 'Nouveau contenu',
});

// Fermer tous les popovers ouverts avec Échap
document.addEventListener('keydown', (evenement) => {
  if (evenement.key !== 'Escape') return;
  document.querySelectorAll('[data-bs-toggle="popover"]').forEach((el) => {
    const instance = bootstrap.Popover.getInstance(el);
    if (instance) instance.hide();
  });
});

Options

Le popover reprend toutes les options des infobulles, avec quatre valeurs par défaut différentes (content, offset, placement, trigger). Les noms d’attributs s’obtiennent en préfixant l’option en kebab-case par data-bs- ; allowList, popperConfig, sanitize, sanitizeFn, selector et template ne se passent pas par attribut.

Options
Option	Type	Défaut	Description
`allowList`	object	liste de balises et d’attributs autorisés	Éléments HTML admis quand `html` est vrai.
`animation`	boolean	`true`	Applique un fondu.
`boundary`	string \| element	`'clippingParents'`	Limite de débordement.
`container`	string \| element \| false	`false`	Insère le popover dans cet élément (utile dans une modale ou un groupe de boutons).
`content`	string \| element \| function	`''`	Contenu du corps du popover.
`customClass`	string \| function	`''`	Classe(s) ajoutée(s) au popover.
`delay`	number \| object	`0`	Délai en ms ; objet `{ show, hide }` pour les distinguer.
`fallbackPlacements`	array	`['top', 'right', 'bottom', 'left']`	Positions de repli.
`html`	boolean	`false`	Interprète titre et contenu comme du HTML.
`offset`	array \| string \| function	`[0, 8]`	Décalage `[saut, distance]`.
`placement`	string \| function	`'right'`	Position : `top`, `right`, `bottom`, `left` ou `auto`.
`popperConfig`	null \| object \| function	`null`	Configuration avancée du positionnement.
`sanitize`	boolean	`true`	Nettoie le HTML. Ne le désactivez jamais avec du contenu saisi par un utilisateur.
`sanitizeFn`	null \| function	`null`	Fonction de nettoyage personnalisée.
`selector`	string \| false	`false`	Délègue le popover à des éléments créés plus tard.
`template`	string	voir ci-dessous	Gabarit : `.popover`, `.popover-arrow`, `.popover-header`, `.popover-body`.
`title`	string \| element \| function	`''`	Titre du popover.
`trigger`	string	`'click'`	Déclencheurs : `click`, `hover`, `focus`, `manual` (séparés par une espace).

Méthodes

Méthodes
Méthode	Description
`show()`	Affiche le popover.
`hide()`	Masque le popover.
`toggle()`	Bascule l’affichage.
`dispose()`	Supprime le popover.
`enable()`	Autorise l’affichage (état par défaut).
`disable()`	Empêche l’affichage.
`toggleEnabled()`	Alterne entre activé et désactivé.
`update()`	Recalcule la position.
`setContent(contenu)`	Remplace le contenu : objet `{ '.popover-header': '…', '.popover-body': '…' }`.
`bootstrap.Popover.getInstance(element)`	Renvoie l’instance liée à l’élément, ou `null`.
`bootstrap.Popover.getOrCreateInstance(element, options)`	Renvoie l’instance, ou la crée.

Événements

Événements
Événement	Déclenché quand
`show.bs.popover`	L’affichage est demandé. Annulable avec `preventDefault()`.
`shown.bs.popover`	Le popover est visible, transition terminée.
`hide.bs.popover`	Le masquage est demandé. Annulable avec `preventDefault()`.
`hidden.bs.popover`	Le popover est masqué, transition terminée.
`inserted.bs.popover`	L’élément du popover vient d’être inséré dans la page.

Attributs data-bs-*

Attributs data-bs-*
Attribut	Option correspondante
`data-bs-toggle="popover"`	Marque l’élément à initialiser.
`data-bs-title`	`title`
`data-bs-content`	`content`
`data-bs-placement`	`placement`
`data-bs-trigger`	`trigger`
`data-bs-html`	`html`
`data-bs-delay`	`delay`
`data-bs-animation`	`animation`
`data-bs-custom-class`	`customClass`
`data-bs-container`	`container`
`data-bs-offset`	`offset`
`data-bs-boundary`	`boundary`
`data-bs-fallback-placements`	`fallbackPlacements`

Variables Sass

Variables Sass
Variable	Valeur par défaut
`$popover-font-size`	`$font-size-sm`
`$popover-bg`	`var(--bs-body-bg)`
`$popover-max-width`	`276px`
`$popover-border-width`	`var(--bs-border-width)`
`$popover-border-color`	`var(--bs-border-color-translucent)`
`$popover-border-radius`	`var(--bs-border-radius-lg)`
`$popover-box-shadow`	`var(--bs-box-shadow)`
`$popover-header-font-size`	`$font-size-base`
`$popover-header-bg`	`var(--bs-secondary-bg)`
`$popover-header-color`	`$headings-color`
`$popover-header-padding-y`	`.5rem`
`$popover-header-padding-x`	`$spacer`
`$popover-body-color`	`var(--bs-body-color)`
`$popover-body-padding-y`	`$spacer`
`$popover-body-padding-x`	`$spacer`
`$popover-arrow-width`	`1rem`
`$popover-arrow-height`	`.5rem`

Personnalisation#

Passez une classe avec customClass et surchargez les variables --bs-popover-* pour modifier une famille de popovers.

// Sass : popovers plus larges
$popover-max-width: 340px;
$popover-body-padding-x: 1.25rem;

// CSS : popover pour l'option customClass: 'popover-bdu'
.popover-bdu {
  --bs-popover-max-width: 340px;
  --bs-popover-header-bg: #2B62AA;
  --bs-popover-header-color: #fff;
  --bs-popover-border-color: #2B62AA;
}

Bonnes pratiques

À faire

Réservez le popover à un complément d’information court : définition, précision sur un tarif, aide à la saisie.
Utilisez un vrai bouton ou lien comme déclencheur, avec un libellé explicite.
Gardez le contenu à quelques lignes et un seul niveau d’information.
Proposez la même information ailleurs dans la page quand elle est importante.

À éviter

N’y placez pas de formulaire ou de contenu long : ouvrez une modale ou un offcanvas.
Ne basez pas une action essentielle (paiement, validation) sur un popover.
N’ouvrez pas plusieurs popovers en même temps : utilisez data-bs-trigger="focus" pour que chacun se ferme tout seul.
N’activez jamais sanitize: false avec un contenu qui vient de l’utilisateur.

Accessibilité

Le déclencheur doit être atteignable au clavier : <button>, <a href> ou un élément avec tabindex="0" et role="button".
Le popover est relié au déclencheur par aria-describedby quand il est ouvert ; son contenu n’est pas piégé au clavier.
Avec trigger: 'hover' seul, le contenu est inaccessible au clavier et au tactile : gardez click ou hover focus.
Échap ne ferme pas un popover par défaut : ajoutez l’écouteur du modèle ci-dessus si vos popovers contiennent des éléments interactifs.