Desplazamiento

Actualice automáticamente la navegación de Bootstrap o enumere los componentes del grupo en función de la posición de desplazamiento para indicar qué enlace está actualmente activo en la ventana gráfica.

En esta página

Cómo funciona

Scrollspy alterna la .activeclase en los elementos ancla ( <a>) cuando el elemento al que idhace referencia el ancla hrefse desplaza a la vista. Scrollspy se usa mejor junto con un componente de navegación Bootstrap o un grupo de listas , pero también funcionará con cualquier elemento de anclaje en la página actual. Así es como funciona.

Para comenzar, scrollspy requiere dos cosas: una navegación, un grupo de listas o un conjunto simple de enlaces, además de un contenedor desplazable. El contenedor desplazable puede ser <body>o un elemento personalizado con un conjunto heighty overflow-y: scroll.
En el contenedor desplazable, agregue data-bs-spy="scroll"y data-bs-target="#navId"dónde navIdestá el único idde la navegación asociada. Asegúrese de incluir también un tabindex="0"para garantizar el acceso al teclado.
A medida que se desplaza por el contenedor "espiado", .activese agrega y elimina una clase de los enlaces de anclaje dentro de la navegación asociada. Los enlaces deben tener iddestinos resolubles, de lo contrario, se ignoran. Por ejemplo, <a href="#home">home</a>debe corresponder a algo en el DOM como<div id="home"></div>
Los elementos de destino que no sean visibles se ignorarán. Consulte la sección Elementos no visibles a continuación.

Ejemplos

Desplácese por el área debajo de la barra de navegación y observe cómo cambia la clase activa. Abra el menú desplegable y observe cómo se resaltan también los elementos desplegables.

primer encabezado

Este es un contenido de marcador de posición para la página scrollspy. Tenga en cuenta que a medida que se desplaza hacia abajo en la página, se resalta el enlace de navegación correspondiente. Se repite en todo el ejemplo del componente. Seguimos agregando más copias de ejemplo aquí para enfatizar el desplazamiento y el resaltado.

Segundo encabezado

Tercer encabezado

Cuarto encabezado

Quinto encabezamiento

<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">First</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#scrollspyHeading2">Second</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">Third</a></li>
        <li><a class="dropdown-item" href="#scrollspyHeading4">Fourth</a></li>
        <li><hr class="dropdown-divider"></li>
        <li><a class="dropdown-item" href="#scrollspyHeading5">Fifth</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">First heading</h4>
  <p>...</p>
  <h4 id="scrollspyHeading2">Second heading</h4>
  <p>...</p>
  <h4 id="scrollspyHeading3">Third heading</h4>
  <p>...</p>
  <h4 id="scrollspyHeading4">Fourth heading</h4>
  <p>...</p>
  <h4 id="scrollspyHeading5">Fifth heading</h4>
  <p>...</p>
</div>

navegación anidada

Scrollspy también funciona con correos electrónicos anidados .nav. Si anidado .naves .active, sus padres también lo serán .active. Desplácese por el área junto a la barra de navegación y observe cómo cambia la clase activa.

Objeto 1

Tenga en cuenta que el complemento de JavaScript intenta elegir el elemento correcto entre todos los que pueden estar visibles. Múltiples objetivos de scrollspy visibles al mismo tiempo pueden causar algunos problemas.

Artículo 1-1

Artículo 1-2

Artículo 2

Artículo 3

Artículo 3-1

Artículo 3-2

<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>

Grupo de lista

Scrollspy también funciona con .list-groups. Desplácese por el área junto al grupo de listas y observe cómo cambia la clase activa.

Objeto 1 Artículo 2 Artículo 3 Artículo 4

Objeto 1

Artículo 2

Artículo 3

Artículo 4

<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>

Anclajes simples

Scrollspy no se limita a componentes de navegación y grupos de listas, por lo que funcionará en cualquier <a>elemento ancla del documento actual. Desplácese por el área y observe cómo .activecambia la clase.

Objeto 1 Artículo 2 Artículo 3 Artículo 4 Artículo 5

Objeto 1

Artículo 2

Artículo 3

Artículo 4

Artículo 5

<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>

Elementos no visibles

Los elementos de destino que no son visibles se ignorarán y sus elementos de navegación correspondientes no recibirán una .activeclase. Las instancias de Scrollspy inicializadas en un envoltorio no visible ignorarán todos los elementos de destino. Utilice el refreshmétodo para buscar elementos observables una vez que el envoltorio sea visible.

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()
  })
})

Uso

A través de atributos de datos

Para agregar fácilmente el comportamiento de scrollspy a la navegación de la barra superior, agregue data-bs-spy="scroll"el elemento que desea espiar (por lo general, este sería el <body>). Luego agregue el data-bs-targetatributo con el idnombre de clase o del elemento principal de cualquier .navcomponente de Bootstrap.

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

A través de JavaScript

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

Opciones

Como las opciones se pueden pasar a través de atributos de datos o JavaScript, puede agregar un nombre de opción a data-bs-, como en data-bs-animation="{value}". Asegúrese de cambiar el tipo de caso del nombre de la opción de " camelCase " a " kebab-case " al pasar las opciones a través de atributos de datos. Por ejemplo, use data-bs-custom-class="beautifier"en lugar de data-bs-customClass="beautifier".

A partir de Bootstrap 5.2.0, todos los componentes admiten un atributo de datos reservados experimentaldata-bs-config que puede albergar una configuración de componente simple como una cadena JSON. Cuando un elemento tiene atributos data-bs-config='{"delay":0, "title":123}'y , el valor final será y los atributos de datos separados anularán los valores dados en . Además, los atributos de datos existentes pueden albergar valores JSON como .data-bs-title="456"title456data-bs-configdata-bs-delay='{"show":0,"hide":150}'

Nombre	Escribe	Defecto	Descripción
`rootMargin`	cuerda	`0px 0px -25%`	Intersection Observer rootMargin unidades válidas, al calcular la posición de desplazamiento.
`smoothScroll`	booleano	`false`	Permite un desplazamiento suave cuando un usuario hace clic en un enlace que se refiere a los observables de ScrollSpy.
`target`	cadena, elemento DOM	`null`	Especifica el elemento para aplicar el complemento Scrollspy.
`threshold`	formación	`[0.1, 0.5, 1]`	`IntersectionObserver` entrada válida de umbral , al calcular la posición de desplazamiento.

Opciones obsoletas

Hasta la versión 5.1.3 usábamos las opciones offset& method, que ahora están obsoletas y reemplazadas por rootMargin. Para mantener la compatibilidad con versiones anteriores, continuaremos analizando un dado offseta rootMargin, pero esta función se eliminará en v6 .

Métodos

Método	Descripción
`dispose`	Destruye el scrollspy de un elemento. (Elimina los datos almacenados en el elemento DOM)
`getInstance`	Método estático para obtener la instancia de scrollspy asociada con un elemento DOM.
`getOrCreateInstance`	Método estático para obtener la instancia de scrollspy asociada con un elemento DOM, o para crear uno nuevo en caso de que no se haya inicializado.
`refresh`	Al agregar o eliminar elementos en el DOM, deberá llamar al método de actualización.

Aquí hay un ejemplo usando el método de actualización:

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

Eventos

Evento	Descripción
`activate.bs.scrollspy`	Este evento se activa en el elemento de desplazamiento cada vez que el scrollspy activa un ancla.

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