Scrollspy

Actualiza automáticamente la navegación de Bootstrap o enumera los componentes de un grupo en función de la posición de desplazamiento para indicar qué enlace está actualmente activo en el viewport.

🎉 ¡La traducción de Bootstrap 5.3 ya se encuentra disponible! (Estás en Bootstrap 5.1)
😎 Esta traducción es parte del proyecto esdocu.com.

En esta página

¿Cómo funciona Scrollspy?

Scrollspy tiene algunos requisitos para funcionar correctamente:

Debe usarse en un componente de navegación o list group de Bootstrap.
Scrollspy requiere position: relative; en el elemento que estás espiando, generalmente el <body>.
Se requieren enlaces (<a>) y deben apuntar a un elemento con ese id.

Cuando se implemente con éxito, tu grupo de navegación o lista se actualizará en consecuencia, moviendo la clase .active de un elemento al siguiente en función de tus objetivos asociados.

Contenedores desplazables y acceso mediante teclado

Si estás creando un contenedor desplazable (que no sea <body>), asegúrate de tener un height y overflow-y: scroll; aplicado, junto con tabindex="0" para garantizar el acceso al teclado.

Desplázate por el área debajo de la barra de navegación y observa cómo cambia la clase activa. Los elementos desplegables también se resaltarán.

Primer encabezado

Este es un contenido placeholder para la página Scrollspy. Ten en cuenta que a medida que te desplazas 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 encabezado

<nav id="navbar-example2" class="navbar navbar-light bg-light px-3">
  <a class="navbar-brand" href="#">Navbar</a>
  <ul class="nav nav-pills">
    <li class="nav-item">
      <a class="nav-link" href="#scrollspyHeading1">Primero</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#scrollspyHeading2">Segundo</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">Tercero</a></li>
        <li><a class="dropdown-item" href="#scrollspyHeading4">Cuarto</a></li>
        <li><hr class="dropdown-divider"></li>
        <li><a class="dropdown-item" href="#scrollspyHeading5">Quinto</a></li>
      </ul>
    </li>
  </ul>
</nav>
<div data-bs-spy="scroll" data-bs-target="#navbar-example2" data-bs-offset="0" class="scrollspy-example" tabindex="0">
  <h4 id="scrollspyHeading1">Primer encabezado</h4>
  <p>...</p>
  <h4 id="scrollspyHeading2">Segundo encabezado</h4>
  <p>...</p>
  <h4 id="scrollspyHeading3">Tercer encabezado</h4>
  <p>...</p>
  <h4 id="scrollspyHeading4">Cuarto encabezado</h4>
  <p>...</p>
  <h4 id="scrollspyHeading5">Quinto encabezado</h4>
  <p>...</p>
</div>

Ejemplo con navegación anidada

Scrollspy también funciona con .navs anidados. Si un .nav anidado es .active, sus padres también serán .active. Desplázate por el área junto a la barra de navegación y observa cómo cambia la clase activa.

Elemento 1

Elemento 1-1

Elemento 1-2

Elemento 2

Elemento 3

Elemento 3-1

Elemento 3-2

<nav id="navbar-example3" class="navbar navbar-light bg-light flex-column align-items-stretch p-3">
  <a class="navbar-brand" href="#">Navbar</a>
  <nav class="nav nav-pills flex-column">
    <a class="nav-link" href="#item-1">Elemento 1</a>
    <nav class="nav nav-pills flex-column">
      <a class="nav-link ms-3 my-1" href="#item-1-1">Elemento 1-1</a>
      <a class="nav-link ms-3 my-1" href="#item-1-2">Elemento 1-2</a>
    </nav>
    <a class="nav-link" href="#item-2">Elemento 2</a>
    <a class="nav-link" href="#item-3">Elemento 3</a>
    <nav class="nav nav-pills flex-column">
      <a class="nav-link ms-3 my-1" href="#item-3-1">Elemento 3-1</a>
      <a class="nav-link ms-3 my-1" href="#item-3-2">Elemento 3-2</a>
    </nav>
  </nav>
</nav>

<div data-bs-spy="scroll" data-bs-target="#navbar-example3" data-bs-offset="0" tabindex="0">
  <h4 id="item-1">Elemento 1</h4>
  <p>...</p>
  <h5 id="item-1-1">Elemento 1-1</h5>
  <p>...</p>
  <h5 id="item-1-2">Elemento 1-2</h5>
  <p>...</p>
  <h4 id="item-2">Elemento 2</h4>
  <p>...</p>
  <h4 id="item-3">Elemento 3</h4>
  <p>...</p>
  <h5 id="item-3-1">Elemento 3-1</h5>
  <p>...</p>
  <h5 id="item-3-2">Elemento 3-2</h5>
  <p>...</p>
</div>

Ejemplo con list-group

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

Elemento 1 Elemento 2 Elemento 3 Elemento 4

Elemento 1

Elemento 2

Elemento 3

Elemento 4

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

Uso

A través de atributos de datos

Para agregar fácilmente el comportamiento de scrollspy a la navegación de la barra superior, agrega data-bs-spy="scroll" al elemento que deseas espiar (por lo general, este sería el <body>). A continuación, agrega el atributo data-bs-target con el ID o la clase del elemento padre de cualquier componente .nav de Bootstrap.

body {
  position: relative;
}

<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

Después de agregar position: relative; en tu CSS, llama a scrollspy a través de JavaScript:

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

Se requieren objetivos de ID resolubles

Los enlaces de la barra de navegación deben tener IDs objetivos resolubles. Por ejemplo, <a href="#home">home</a> debe corresponder a algo en el DOM como <div id="home"></div>.

Se ignoran los elementos objetivos no visibles

Los elementos de destino que no sean visibles se ignorarán y sus elementos de navegación correspondientes nunca se resaltarán.

Métodos

refresh

Cuando uses scrollspy junto con la adición o eliminación de elementos del DOM, deberás llamar al método de actualización de la siguiente manera:

var dataSpyList = Array.prototype.slice.call(document.querySelectorAll('[data-bs-spy="scroll"]'))
dataSpyList.forEach(function (dataSpyEl) {
  bootstrap.ScrollSpy.getInstance(dataSpyEl)
    .refresh()
})

dispose

Destruye el scrollspy de un elemento. (Elimina los datos almacenados en el elemento DOM)

getInstance

Método estático que te permite obtener la instancia de scrollspy asociada con un elemento DOM

var scrollSpyContentEl = document.getElementById('content')
var scrollSpy = bootstrap.ScrollSpy.getInstance(scrollSpyContentEl) // Returns a Bootstrap scrollspy instance

getOrCreateInstance

Método estático que te permite obtener la instancia de scrollspy asociada con un elemento DOM, o crear una nueva en caso de que no se haya inicializado

var scrollSpyContentEl = document.getElementById('content')
var scrollSpy = bootstrap.ScrollSpy.getOrCreateInstance(scrollSpyContentEl) // Returns a Bootstrap scrollspy instance

Opciones

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-bs-, as in data-bs-offset="".

Nombre	Tipo	Por defecto	Descripción
`offset`	number	`10`	Píxeles para compensar desde la parte superior al calcular la posición de desplazamiento.
`method`	string	`auto`	Encuentra en qué sección se encuentra el elemento espiado. `auto` elegirá el mejor método para obtener las coordenadas de desplazamiento. `offset` utilizará el método `Element.getBoundingClientRect()` para obtener las coordenadas de desplazamiento. `position` usará las propiedades `HTMLElement.offsetTop` y `HTMLElement.offsetLeft` para obtener las coordenadas de desplazamiento.
`target`	string \| jQuery object \| DOM element		Especifica el elemento para aplicar el complemento Scrollspy.

Eventos

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

var firstScrollSpyEl = document.querySelector('[data-bs-spy="scroll"]')
firstScrollSpyEl.addEventListener('activate.bs.scrollspy', function () {
  // hacer algo...
})

🎉 ¡La traducción de Bootstrap 5.3 ya se encuentra disponible! (Estás en Bootstrap 5.1)
😎 Esta traducción es parte del proyecto esdocu.com.

Scrollspy

¿Cómo funciona Scrollspy?

Contenedores desplazables y acceso mediante teclado

Ejemplo en navbar

Primer encabezado

Segundo encabezado

Tercer encabezado

Cuarto encabezado

Quinto encabezado

Ejemplo con navegación anidada

Elemento 1

Elemento 1-1

Elemento 1-2

Elemento 2

Elemento 3

Elemento 3-1

Elemento 3-2

Ejemplo con list-group

Elemento 1

Elemento 2

Elemento 3

Elemento 4

Uso

A través de atributos de datos

A través de JavaScript

Se requieren objetivos de ID resolubles

Se ignoran los elementos objetivos no visibles

Métodos

refresh

dispose

getInstance

getOrCreateInstance

Opciones

Eventos