ComposantsJavaScript requis
Infobulles
Une infobulle est une courte aide contextuelle qui apparaît au survol ou au focus d’un élément. Elle complète une information déjà présente, sans jamais en être la seule source.
Initialisation#
Les infobulles ne s’activent pas toutes seules : initialisez-les une fois la page chargée. Le site de cette documentation le fait déjà pour les aperçus.
const declencheurs = document.querySelectorAll('[data-bs-toggle="tooltip"]');
declencheurs.forEach((element) => new bootstrap.Tooltip(element));Exemple de base#
Ajoutez data-bs-toggle="tooltip" et le texte dans title (ou data-bs-title). Le texte apparaît au survol et au focus clavier.
<button type="button" class="btn btn-outline-primary" data-bs-toggle="tooltip" data-bs-title="Votre IBAN est affiché sur le relevé d'identité bancaire">IBAN</button>
<a href="#" class="btn btn-link" data-bs-toggle="tooltip" data-bs-title="Les virements instantanés sont traités en quelques secondes">Virement instantané</a>Positions#
data-bs-placement accepte top (valeur par défaut), right, bottom et left. Si la place manque, l’infobulle bascule de l’autre côté.
<div class="d-flex flex-wrap gap-2">
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="top" data-bs-title="Au-dessus">Haut</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="right" data-bs-title="À droite">Droite</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="bottom" data-bs-title="En dessous">Bas</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="left" data-bs-title="À gauche">Gauche</button>
</div>Contenu HTML et classe personnalisée#
Avec data-bs-html="true", le titre peut contenir du HTML simple (le contenu est nettoyé pour des raisons de sécurité). data-bs-custom-class ajoute une classe à l’infobulle.
<button type="button" class="btn btn-outline-primary" data-bs-toggle="tooltip" data-bs-html="true" data-bs-title="<strong>Plafond</strong><br>500 000 FCFA par jour">Plafond de retrait</button>
<button type="button" class="btn btn-outline-primary" data-bs-toggle="tooltip" data-bs-custom-class="info-large" data-bs-title="Infobulle avec une classe supplémentaire">Classe personnalisée</button>Éléments désactivés et icônes#
Un bouton désactivé ne reçoit ni survol ni focus. Enveloppez-le dans un élément focalisable (tabindex="0") qui porte l’infobulle. Pour un bouton-icône, ajoutez toujours un aria-label.
<span class="d-inline-block" tabindex="0" data-bs-toggle="tooltip" data-bs-title="Disponible après validation de votre dossier">
<button class="btn btn-primary" type="button" disabled style="pointer-events: none;">Souscrire</button>
</span>
<button type="button" class="btn btn-outline-secondary" aria-label="Copier l'IBAN" data-bs-toggle="tooltip" data-bs-title="Copier l'IBAN">
<svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><rect x="5" y="5" width="8" height="9" rx="1"/><path d="M3 11V3a1 1 0 0 1 1-1h7"/></svg>
</button>Options passées en JavaScript#
Les options peuvent aussi être fournies à la création. Elles priment sur les attributs data-bs-*.
const infobulle = new bootstrap.Tooltip('#bouton-iban', {
title: 'Copié dans le presse-papiers',
placement: 'bottom',
trigger: 'click',
delay: { show: 300, hide: 100 },
});
infobulle.show();
infobulle.setContent({ '.tooltip-inner': 'IBAN copié' });Options
Les options se passent au constructeur ou par un attribut data-bs-* (le nom devient data-bs- suivi de l’option en kebab-case, par exemple data-bs-custom-class). Les options allowList, popperConfig, sanitize, sanitizeFn, selector et template ne se passent pas par attribut.
| Option | Type | Défaut | Description |
|---|---|---|---|
allowList | object | liste de balises et d’attributs autorisés | Éléments HTML admis dans le titre quand html est vrai. |
animation | boolean | true | Applique un fondu à l’apparition. |
boundary | string | element | 'clippingParents' | Limite de débordement pour le positionnement. |
container | string | element | false | false | Ajoute l’infobulle à cet élément au lieu de la placer après le déclencheur. |
customClass | string | function | '' | Classe(s) ajoutée(s) à l’infobulle. |
delay | number | object | 0 | Délai en ms avant affichage et masquage ; objet { show, hide } pour les distinguer. |
fallbackPlacements | array | ['top', 'right', 'bottom', 'left'] | Positions de repli quand la place manque. |
html | boolean | false | Interprète le titre comme du HTML. |
offset | array | string | function | [0, 6] | Décalage [saut, distance] par rapport au déclencheur. |
placement | string | function | 'top' | Position : top, right, bottom, left ou auto. |
popperConfig | null | object | function | null | Configuration avancée du moteur de positionnement. |
sanitize | boolean | true | Nettoie le HTML du titre. Ne désactivez jamais cette option avec du contenu saisi par un utilisateur. |
sanitizeFn | null | function | null | Fonction de nettoyage personnalisée. |
selector | string | false | false | Délègue l’infobulle à des éléments créés plus tard à l’intérieur de la cible. |
template | string | voir ci-dessous | Gabarit HTML de l’infobulle (.tooltip, .tooltip-arrow, .tooltip-inner). |
title | string | element | function | '' | Texte de l’infobulle ; repris de l’attribut title s’il est vide. |
trigger | string | 'hover focus' | Déclencheurs, séparés par une espace : click, hover, focus, manual. |
Méthodes
Récupérez l’instance avec bootstrap.Tooltip.getOrCreateInstance(element). Les méthodes d’affichage rendent la main avant la fin de la transition : écoutez shown.bs.tooltip ou hidden.bs.tooltip pour agir ensuite.
| Méthode | Description |
|---|---|
show() | Affiche l’infobulle. |
hide() | Masque l’infobulle. |
toggle() | Bascule l’affichage. |
dispose() | Supprime l’infobulle et libère l’élément. |
enable() | Autorise l’affichage (état par défaut). |
disable() | Empêche l’affichage tant que enable() n’est pas appelé. |
toggleEnabled() | Alterne entre activée et désactivée. |
update() | Recalcule la position. |
setContent(contenu) | Remplace le contenu ; passez un objet de la forme { '.tooltip-inner': 'Nouveau texte' }. |
bootstrap.Tooltip.getInstance(element) | Renvoie l’instance liée à l’élément, ou null. |
bootstrap.Tooltip.getOrCreateInstance(element, options) | Renvoie l’instance, ou la crée si elle n’existe pas. |
Événements
| Événement | Déclenché quand |
|---|---|
show.bs.tooltip | L’affichage est demandé (avant l’animation). Annulable avec preventDefault(). |
shown.bs.tooltip | L’infobulle est visible, transition terminée. |
hide.bs.tooltip | Le masquage est demandé. Annulable avec preventDefault(). |
hidden.bs.tooltip | L’infobulle est masquée, transition terminée. |
inserted.bs.tooltip | L’élément de l’infobulle vient d’être inséré dans la page, après show.bs.tooltip. |
Attributs data-bs-*
| Attribut | Option correspondante |
|---|---|
data-bs-toggle="tooltip" | Marque l’élément à initialiser (sélecteur à utiliser dans votre script). |
data-bs-title | title (préférable à l’attribut title, qui est repris puis retiré). |
data-bs-placement | placement |
data-bs-html | html |
data-bs-trigger | trigger |
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
| Variable | Valeur par défaut |
|---|---|
$tooltip-font-size | $font-size-sm |
$tooltip-max-width | 200px |
$tooltip-color | var(--bs-body-bg) |
$tooltip-bg | var(--bs-emphasis-color) |
$tooltip-border-radius | var(--bs-border-radius) |
$tooltip-opacity | .9 |
$tooltip-padding-y | $spacer * .25 |
$tooltip-padding-x | $spacer * .5 |
$tooltip-arrow-width | .8rem |
$tooltip-arrow-height | .4rem |
Personnalisation#
Une classe passée par customClass permet de modifier une seule famille d’infobulles avec les variables CSS --bs-tooltip-*.
// Sass : infobulles plus larges
$tooltip-max-width: 280px;
$tooltip-font-size: 0.875rem;
// CSS : infobulle bleue pour l'option customClass: 'info-bdu'
.info-bdu {
--bs-tooltip-bg: #2B62AA;
--bs-tooltip-color: #fff;
--bs-tooltip-opacity: 1;
--bs-tooltip-max-width: 280px;
}Bonnes pratiques
À faire
- Gardez le texte très court (une phrase au plus) et utile : précision, unité, raccourci.
- Placez l’infobulle sur un élément qui reçoit déjà le focus (bouton, lien, champ).
- Pour un bouton-icône, donnez un
aria-labelet répétez-le dans l’infobulle. - Prévoyez une alternative visible pour l’information importante (texte d’aide sous le champ).
À éviter
- Ne placez jamais une information indispensable (frais, conditions, avertissement) uniquement dans une infobulle.
- Ne mettez pas de liens ni de boutons dans une infobulle : elle disparaît dès que le pointeur la quitte. Utilisez un popover.
- N’ajoutez pas d’infobulle sur un élément non focalisable (
<span>,<div>) sanstabindex="0".
Accessibilité
- Par défaut, l’infobulle s’affiche au survol et au focus : elle reste donc accessible au clavier. Ne retirez pas le déclencheur
focus. - Le texte est relié au déclencheur par
aria-describedbyquand l’infobulle est affichée. - Sur un élément non natif (
<span>,<div>), ajouteztabindex="0"pour que le clavier atteigne l’infobulle. - Une infobulle disparaît dès que le focus ou le pointeur la quitte : ne l’utilisez pas pour du contenu à lire lentement ou à copier.