Bootstrap 5.2 / Componenten

Scrollspy

Werk Bootstrap-navigatie- of list group-componenten automatisch bij op basis van de scrollpositie, om aan te geven welke link momenteel actief is in de viewport.

Hoe het werkt

Scrollspy schakelt de klasse .active op anker-elementen (<a>) wanneer het element met de id waarnaar de href van het anker verwijst in beeld scrollt. Scrollspy gebruik je het best in combinatie met een Bootstrap-nav-component of list group, maar hij werkt ook met willekeurige anker-elementen op de huidige pagina. Zo werkt het.

Om te beginnen heeft scrollspy twee dingen nodig: een navigatie, list group of eenvoudige set links, plus een scrollbare container. De scrollbare container kan de <body> zijn of een eigen element met een ingestelde height en overflow-y: scroll.
Voeg op de scrollbare container data-bs-spy="scroll" en data-bs-target="#navId" toe, waarbij navId de unieke id van de bijbehorende navigatie is. Voeg ook een tabindex="0" toe om toetsenbordtoegang te garanderen.
Terwijl je door de "bespiede" container scrollt, wordt de klasse .active toegevoegd aan en verwijderd van ankerlinks in de bijbehorende navigatie. Links moeten oplosbare id-doelen hebben, anders worden ze genegeerd. Zo hoort bij <a href="#home">home</a> iets in de DOM als <div id="home"></div> te bestaan.
Doelelementen die niet zichtbaar zijn worden genegeerd. Zie het onderdeel Niet-zichtbare elementen hieronder.

Voorbeelden

Scroll door het gebied onder de navbar en zie de active-klasse veranderen. Open het dropdownmenu en zie ook de dropdown-items uitgelicht worden.

Eerste kop

Dit is wat opvulcontent voor de scrollspy-pagina. Let op: terwijl je omlaag scrollt, wordt de bijbehorende navigatielink uitgelicht. Dit herhaalt zich door het hele componentvoorbeeld heen. We voegen hier steeds wat meer voorbeeldtekst toe om het scrollen en uitlichten te benadrukken.

Tweede kop

Derde kop

Vierde kop

Vijfde kop

HTML

<nav id="navbar-example2" class="navbar bg-light px-3 mb-3">
  <a class="navbar-brand" href="#">Navbar</a>
  <ul class="nav nav-pills">
    <li class="nav-item">
      <a class="nav-link" href="#scrollspyHeading1">Eerste</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#scrollspyHeading2">Tweede</a>
    </li>
    <li class="nav-item dropdown">
      <a class="nav-link dropdown-toggle" data-bs-toggle="dropdown" href="#" role="button" aria-expanded="false">Dropdown</a>
      <ul class="dropdown-menu">
        <li><a class="dropdown-item" href="#scrollspyHeading3">Derde</a></li>
        <li><a class="dropdown-item" href="#scrollspyHeading4">Vierde</a></li>
        <li><hr class="dropdown-divider"></li>
        <li><a class="dropdown-item" href="#scrollspyHeading5">Vijfde</a></li>
      </ul>
    </li>
  </ul>
</nav>
<div data-bs-spy="scroll" data-bs-target="#navbar-example2" data-bs-root-margin="0px 0px -40%" data-bs-smooth-scroll="true" class="scrollspy-example bg-light p-3 rounded-2" tabindex="0">
  <h4 id="scrollspyHeading1">Eerste kop</h4>
  <p>...</p>
  <h4 id="scrollspyHeading2">Tweede kop</h4>
  <p>...</p>
  <h4 id="scrollspyHeading3">Derde kop</h4>
  <p>...</p>
  <h4 id="scrollspyHeading4">Vierde kop</h4>
  <p>...</p>
  <h4 id="scrollspyHeading5">Vijfde kop</h4>
  <p>...</p>
</div>

Geneste nav

Scrollspy werkt ook met geneste .navs. Is een geneste .nav .active, dan worden de bovenliggende elementen ook .active. Scroll door het gebied naast de navbar en zie de active-klasse veranderen.

Item 1

Houd er rekening mee dat de JavaScript-plugin probeert het juiste element te kiezen uit alle elementen die zichtbaar kunnen zijn. Meerdere tegelijk zichtbare scrollspy-doelen kunnen problemen veroorzaken.

Item 1-1

Item 1-2

Item 2

Item 3

Item 3-1

Item 3-2

HTML

<div class="row">
  <div class="col-4">
    <nav id="navbar-example3" class="h-100 flex-column align-items-stretch pe-4 border-end">
      <nav class="nav nav-pills flex-column">
        <a class="nav-link" href="#item-1">Item 1</a>
        <nav class="nav nav-pills flex-column">
          <a class="nav-link ms-3 my-1" href="#item-1-1">Item 1-1</a>
          <a class="nav-link ms-3 my-1" href="#item-1-2">Item 1-2</a>
        </nav>
        <a class="nav-link" href="#item-2">Item 2</a>
        <a class="nav-link" href="#item-3">Item 3</a>
        <nav class="nav nav-pills flex-column">
          <a class="nav-link ms-3 my-1" href="#item-3-1">Item 3-1</a>
          <a class="nav-link ms-3 my-1" href="#item-3-2">Item 3-2</a>
        </nav>
      </nav>
    </nav>
  </div>

  <div class="col-8">
    <div data-bs-spy="scroll" data-bs-target="#navbar-example3" data-bs-smooth-scroll="true" class="scrollspy-example-2" tabindex="0">
      <div id="item-1">
        <h4>Item 1</h4>
        <p>...</p>
      </div>
      <div id="item-1-1">
        <h5>Item 1-1</h5>
        <p>...</p>
      </div>
      <div id="item-1-2">
        <h5>Item 1-2</h5>
        <p>...</p>
      </div>
      <div id="item-2">
        <h4>Item 2</h4>
        <p>...</p>
      </div>
      <div id="item-3">
        <h4>Item 3</h4>
        <p>...</p>
      </div>
      <div id="item-3-1">
        <h5>Item 3-1</h5>
        <p>...</p>
      </div>
      <div id="item-3-2">
        <h5>Item 3-2</h5>
        <p>...</p>
      </div>
    </div>
  </div>
</div>

List group

Scrollspy werkt ook met .list-groups. Scroll door het gebied naast de list group en zie de active-klasse veranderen.

Item 1 Item 2 Item 3 Item 4

Item 1

Item 2

Item 3

Item 4

HTML

<div class="row">
  <div class="col-4">
    <div id="list-example" class="list-group">
      <a class="list-group-item list-group-item-action" href="#list-item-1">Item 1</a>
      <a class="list-group-item list-group-item-action" href="#list-item-2">Item 2</a>
      <a class="list-group-item list-group-item-action" href="#list-item-3">Item 3</a>
      <a class="list-group-item list-group-item-action" href="#list-item-4">Item 4</a>
    </div>
  </div>
  <div class="col-8">
    <div data-bs-spy="scroll" data-bs-target="#list-example" data-bs-smooth-scroll="true" class="scrollspy-example" tabindex="0">
      <h4 id="list-item-1">Item 1</h4>
      <p>...</p>
      <h4 id="list-item-2">Item 2</h4>
      <p>...</p>
      <h4 id="list-item-3">Item 3</h4>
      <p>...</p>
      <h4 id="list-item-4">Item 4</h4>
      <p>...</p>
    </div>
  </div>
</div>

Eenvoudige ankers

Scrollspy is niet beperkt tot nav-componenten en list groups; hij werkt op alle <a>-anker-elementen in het huidige document. Scroll door het gebied en zie de klasse .active veranderen.

Item 1 Item 2 Item 3 Item 4 Item 5

Item 1

Item 2

Item 3

Item 4

Item 5

HTML

<div class="row">
  <div class="col-4">
    <div id="simple-list-example" class="d-flex flex-column gap-2 simple-list-example-scrollspy text-center">
      <a class="p-1 rounded" href="#simple-list-item-1">Item 1</a>
      <a class="p-1 rounded" href="#simple-list-item-2">Item 2</a>
      <a class="p-1 rounded" href="#simple-list-item-3">Item 3</a>
      <a class="p-1 rounded" href="#simple-list-item-4">Item 4</a>
      <a class="p-1 rounded" href="#simple-list-item-5">Item 5</a>
    </div>
  </div>
  <div class="col-8">
    <div data-bs-spy="scroll" data-bs-target="#simple-list-example" data-bs-offset="0" data-bs-smooth-scroll="true" class="scrollspy-example" tabindex="0">
      <h4 id="simple-list-item-1">Item 1</h4>
      <p>...</p>
      <h4 id="simple-list-item-2">Item 2</h4>
      <p>...</p>
      <h4 id="simple-list-item-3">Item 3</h4>
      <p>...</p>
      <h4 id="simple-list-item-4">Item 4</h4>
      <p>...</p>
      <h4 id="simple-list-item-5">Item 5</h4>
      <p>...</p>
    </div>
  </div>
</div>

Niet-zichtbare elementen

Doelelementen die niet zichtbaar zijn worden genegeerd en hun bijbehorende nav-items krijgen geen .active-klasse. Scrollspy-instanties die in een niet-zichtbare wrapper zijn geïnitialiseerd, negeren alle doelelementen. Gebruik de methode refresh om op waarneembare elementen te controleren zodra de wrapper zichtbaar wordt.

document.querySelectorAll('#nav-tab>[data-bs-toggle="tab"]').forEach(el => {
  el.addEventListener('shown.bs.tab', () => {
    const target = el.getAttribute('data-bs-target')
    const scrollElem = document.querySelector(`${target} [data-bs-spy="scroll"]`)
    bootstrap.ScrollSpy.getOrCreateInstance(scrollElem).refresh()
  })
})

Gebruik

Via data-attributen

Om scrollspy-gedrag eenvoudig aan je bovenbalknavigatie toe te voegen, voeg je data-bs-spy="scroll" toe aan het element dat je wilt bespieden (meestal is dat de <body>). Voeg daarna het attribuut data-bs-target toe met de id of klassenaam van het bovenliggende element van een Bootstrap-.nav-component.

HTML

<body data-bs-spy="scroll" data-bs-target="#navbar-example">
  ...
  <div id="navbar-example">
    <ul class="nav nav-tabs" role="tablist">
      ...
    </ul>
  </div>
  ...
</body>

Via JavaScript

const scrollSpy = new bootstrap.ScrollSpy(document.body, {
  target: '#navbar-example'
})

Opties

De meeste plugins kun je aanzetten zonder JavaScript te schrijven, puur met een data-bs-*-attribuut als trigger. Al deze data-attributen zijn genamespaced met bs-, zodat ze niet botsen met andere scripts.

Naam	Type	Standaard	Omschrijving
`rootMargin`	string	`0px 0px -25%`	Geldige eenheden voor de Intersection Observer-rootMargin, bij het berekenen van de scrollpositie.
`smoothScroll`	boolean	`false`	Schakelt vloeiend scrollen in wanneer een gebruiker op een link klikt die naar ScrollSpy-waarneembare elementen verwijst.
`target`	string, DOM-element	`null`	Geeft aan op welk element de Scrollspy-plugin moet worden toegepast.
`threshold`	array	`[0.1, 0.5, 1]`	Geldige invoer voor de `IntersectionObserver`-threshold, bij het berekenen van de scrollpositie.

Let op

Verouderde opties

Tot en met v5.1.3 gebruikten we de opties offset en method; die zijn nu verouderd en vervangen door rootMargin. Voor achterwaartse compatibiliteit blijven we een opgegeven offset naar rootMargin omzetten, maar deze functionaliteit wordt in v6 verwijderd.

Methodes

Methode	Omschrijving
`dispose`	Vernietigt de scrollspy van een element. (Verwijdert opgeslagen gegevens van het DOM-element)
`getInstance`	Statische methode om de scrollspy-instantie op te halen die bij een DOM-element hoort.
`getOrCreateInstance`	Statische methode om de scrollspy-instantie op te halen die bij een DOM-element hoort, of een nieuwe aan te maken als die nog niet was geïnitialiseerd.
`refresh`	Wanneer je elementen aan de DOM toevoegt of eruit verwijdert, moet je de refresh-methode aanroepen.

Hier is een voorbeeld met de refresh-methode:

const dataSpyList = document.querySelectorAll('[data-bs-spy="scroll"]')
dataSpyList.forEach(dataSpyEl => {
  bootstrap.ScrollSpy.getInstance(dataSpyEl).refresh()
})

Gebeurtenissen

Gebeurtenis	Omschrijving
`activate.bs.scrollspy`	Deze gebeurtenis wordt op het scroll-element afgevuurd zodra een anker door de scrollspy wordt geactiveerd.

const firstScrollSpyEl = document.querySelector('[data-bs-spy="scroll"]')
firstScrollSpyEl.addEventListener('activate.bs.scrollspy', () => {
  // doe iets...
})