Scrollspy
Scrollspy met à jour automatiquement une navigation selon la section visible dans une zone qui défile. Il convient à une page longue avec sommaire : conditions générales, aide, fiche produit.
Exemple avec une barre de navigation#
Ajoutez data-bs-spy="scroll" et data-bs-target (sélecteur de la navigation) sur la zone qui défile. Chaque lien de la navigation pointe vers l'id d’une section. Ici la zone a une hauteur fixe et tabindex="0", pour être atteignable au clavier.
Avec un groupe de liste#
Scrollspy fonctionne aussi avec .list-group ; chaque .list-group-item-action doit pointer vers une section.
Le livret rémunéré à 3,5 % par an accepte des versements libres dès 5 000 FCFA. Les retraits restent possibles à tout moment, sans pénalité.
Le prêt personnel finance vos projets jusqu'à 10 000 000 FCFA, sur 12 à 60 mois, avec des mensualités constantes.
L'assurance emprunteur protège vos proches en cas de décès ou d'invalidité pendant la durée du prêt.
<div class="row g-3">
<div class="col-4">
<div id="spy-liste" class="list-group">
<a class="list-group-item list-group-item-action" href="#spy-liste-epargne">Épargne</a>
<a class="list-group-item list-group-item-action" href="#spy-liste-credit">Crédit</a>
<a class="list-group-item list-group-item-action" href="#spy-liste-assurance">Assurance</a>
</div>
</div>
<div class="col-8">
<div data-bs-spy="scroll" data-bs-target="#spy-liste" data-bs-smooth-scroll="true" class="border rounded p-3 overflow-auto" style="height: 180px;" tabindex="0">
<h4 id="spy-liste-epargne">Épargne</h4>
<p>Le livret rémunéré à 3,5 % par an accepte des versements libres dès 5 000 FCFA. Les retraits restent possibles à tout moment, sans pénalité.</p>
<h4 id="spy-liste-credit">Crédit</h4>
<p>Le prêt personnel finance vos projets jusqu'à 10 000 000 FCFA, sur 12 à 60 mois, avec des mensualités constantes.</p>
<h4 id="spy-liste-assurance">Assurance</h4>
<p>L'assurance emprunteur protège vos proches en cas de décès ou d'invalidité pendant la durée du prêt.</p>
</div>
</div>
</div>Navigation imbriquée#
Une navigation à deux niveaux est prise en charge : quand une sous-section devient active, son parent est aussi mis en évidence.
Utilisation en JavaScript#
Créez l’instance vous-même pour surveiller le body ou un conteneur précis. Si vous ajoutez ou retirez des sections après la création, appelez refresh().
const spy = new bootstrap.ScrollSpy(document.body, {
target: '#sommaire',
rootMargin: '0px 0px -25%',
smoothScroll: true,
});
// Après avoir ajouté des sections dans la page
spy.refresh();
document.addEventListener('activate.bs.scrollspy', (evenement) => {
console.log('Lien actif : ' + evenement.relatedTarget.textContent);
});Options
Les options se passent au constructeur ou par attribut. Le nom d’attribut est data-bs- suivi de l’option en kebab-case (data-bs-root-margin).
| Option | Type | Défaut | Description |
|---|---|---|---|
rootMargin | string | '0px 0px -25%' | Marges de la zone d’observation (syntaxe CSS). Les valeurs négatives en bas rendent active une section plus tôt. |
smoothScroll | boolean | false | Défilement doux quand on clique sur un lien de la navigation. |
target | string | element | null | Navigation à mettre à jour (obligatoire). |
threshold | array | [0.1, 0.5, 1] | Seuils de visibilité (de 0 à 1) qui déclenchent la mise à jour. |
offset | number | null | Obsolète : conservée pour compatibilité, utilisez rootMargin. |
Méthodes
| Méthode | Description |
|---|---|
refresh() | Recalcule les sections observées. À appeler après un ajout ou un retrait de sections. |
dispose() | Détruit l’instance. |
bootstrap.ScrollSpy.getInstance(element) | Renvoie l’instance liée à l’élément, ou null. |
bootstrap.ScrollSpy.getOrCreateInstance(element, options) | Renvoie l’instance, ou la crée. |
Événements
| Événement | Déclenché quand |
|---|---|
activate.bs.scrollspy | Un lien de la navigation devient actif. relatedTarget désigne ce lien. L’événement est émis sur la zone surveillée et remonte dans le document. |
Attributs data-bs-*
| Attribut | Effet |
|---|---|
data-bs-spy="scroll" | Active scrollspy sur la zone qui défile (ou sur le body). |
data-bs-target | Sélecteur de la navigation (.nav, .list-group ou nav contenant des liens). |
data-bs-root-margin | Option rootMargin. |
data-bs-smooth-scroll | Option smoothScroll. |
data-bs-threshold | Option threshold (valeurs séparées par des virgules). |
Variables Sass liées
Scrollspy n’a pas de variable propre : l’aspect du lien actif vient de la navigation ou du groupe de liste cible.
| Variable | Valeur par défaut | Effet |
|---|---|---|
$nav-pills-link-active-bg | $component-active-bg | Fond du lien actif d’une navigation en pilules. |
$nav-pills-link-active-color | $component-active-color | Texte du lien actif d’une navigation en pilules. |
$nav-link-padding-x | 1rem | Espacement horizontal des liens. |
$list-group-active-bg | $component-active-bg | Fond de l’élément actif d’un groupe de liste. |
$list-group-active-color | $component-active-color | Texte de l’élément actif d’un groupe de liste. |
Personnalisation#
Pour que les titres ne passent pas sous une barre fixe lors du défilement doux, ajoutez une marge de défilement aux sections.
// Sass : lien actif vert
$nav-pills-link-active-bg: $success;
$list-group-active-bg: $success;
// CSS : décalage des ancres sous une barre fixe de 4 rem
[data-bs-spy="scroll"] [id] {
scroll-margin-top: 4rem;
}Bonnes pratiques
À faire
- Donnez à chaque section un
idunique et faites pointer un lien de la navigation vers lui. - Fixez une hauteur et
overflow-autosur la zone qui défile, avectabindex="0"pour l’atteindre au clavier. - Appelez
refresh()après chaque ajout ou suppression de section. - Gardez des sections assez hautes pour que chacune puisse devenir active.
À éviter
- Ne faites pas dépendre l’accès au contenu de la navigation : tout doit rester lisible sans elle.
- N’imbriquez pas plus de deux niveaux de navigation.
- Ne réutilisez pas le même
iddans la page : le lien désignerait la mauvaise section.
Accessibilité
- La zone qui défile doit être focalisable (
tabindex="0") pour que le clavier puisse la faire défiler. - Entourez la navigation d’un
<nav>avec unaria-label, par exemple « Sommaire du guide ». - Le lien actif est mis en évidence par la classe
.active: n’ajoutez pasaria-currentà la main, il n’est pas géré par scrollspy. - Le défilement doux (
smoothScroll) anime la page : laissez-le désactivé si vos utilisateurs préfèrent moins de mouvement.