Propiedad CSS scroll-behavior
Usa la propiedad CSS scroll-behavior para especificar el comportamiento del desplazamiento. Consulta los valores y ejemplos.
La propiedad CSS scroll-behavior define si un desplazamiento activado por la navegación o por un script (una "caja de desplazamiento" que salta a un ancla o a una coordenada) debe ser suave (animado) o instantáneo (un salto único). Por defecto es auto, lo que significa un salto abrupto.
Esta página explica qué hace la propiedad, dónde debes declararla, la diferencia entre sus valores, errores comunes y cómo se relaciona con las APIs de desplazamiento de JavaScript.
¿Cuándo usarla?
El caso de uso más común es la navegación dentro de la misma página. Cuando un enlace apunta a un fragmento como <a href="#section">, el navegador normalmente salta instantáneamente al destino. Establecer scroll-behavior: smooth en el contenedor de desplazamiento convierte ese salto en un desplazamiento animado y agradable, sin una sola línea de JavaScript.
html {
scroll-behavior: smooth;
}Dónde declararla
Hay dos reglas que suelen confundir a los desarrolladores:
- Solo afecta a los desplazamientos programáticos y activados por navegación: hacer clic en un ancla, llamar a
element.scrollIntoView(),window.scrollTo(), etc. No tiene efecto en los desplazamientos que realiza el usuario con la rueda del ratón, el trackpad o la barra de desplazamiento. - Para el desplazamiento del viewport, declárala en
html, no enbody. El valor declarado en el elemento body no se propaga al viewport, por lo que sería ignorado. Declárala en el elemento html (la caja de desplazamiento raíz). Para cualquier otro contenedor desplazable, declárala en ese contenedor directamente.
Los agentes de usuario pueden ignorar esta propiedad, y se omitirá para los usuarios que soliciten movimiento reducido (consulta Accesibilidad más abajo).
| Valor inicial | auto |
|---|---|
| Se aplica a | Cajas de desplazamiento. |
| Heredada | No. |
| Animable | No. |
| Versión | CSSOM View Module (Working Draft) |
| Sintaxis DOM | object.style.scrollBehavior = "smooth"; |
Sintaxis
Sintaxis CSS de scroll-behavior
scroll-behavior: auto | smooth | initial | inherit;Ejemplo de la propiedad scroll-behavior con el valor "auto":
Ejemplo de código CSS scroll-behavior
<!DOCTYPE html>
<html>
<head>
<title>Title of the document</title>
<style>
html {
scroll-behavior: auto;
}
#element1 {
height: 600px;
background-color: #ccc;
}
#element2 {
height: 600px;
background-color: #8ebf42;
}
</style>
</head>
<body>
<h2>Scroll-behavior property example</h2>
<div class="main" id="element1">
<h2>Element 1</h2>
<a href="#element2">Click to scroll to Element 2</a>
</div>
<div class="main" id="element2">
<h2>Element 2</h2>
<a href="#element1">Click to scroll to Element 1</a>
</div>
</body>
</html>Ejemplo de la propiedad scroll-behavior con el valor "smooth":
Ejemplo CSS scroll-behavior con el valor smooth
<!DOCTYPE html>
<html>
<head>
<title>Title of the document</title>
<style>
html {
scroll-behavior: smooth;
}
#element1 {
height: 600px;
background-color: #ccc;
}
#element2 {
height: 600px;
background-color: #8ebf42;
}
</style>
</head>
<body>
<h2>Scroll-behavior property example</h2>
<div class="main" id="element1">
<h2>Element 1</h2>
<a href="#element2">Click to scroll to Element 2</a>
</div>
<div class="main" id="element2">
<h2>Element 2</h2>
<a href="#element1">Click to scroll to Element 1</a>
</div>
</body>
</html>Con smooth, al hacer clic en cualquiera de los enlaces se anima la página entre los dos bloques en lugar de saltar instantáneamente. Solo el valor de scroll-behavior difiere del ejemplo anterior.
Valores
| Valor | Descripción |
|---|---|
| auto | Predeterminado. El desplazamiento ocurre en un único salto instantáneo, sin animación. |
| smooth | El desplazamiento se anima de forma suave entre las posiciones de inicio y fin. |
| initial | Establece la propiedad a su valor predeterminado (auto). |
| inherit | Hereda el valor del elemento padre. |
Suavizar un contenedor específico
scroll-behavior no se limita a la página. Declárala en cualquier elemento que tenga su propia barra de desplazamiento (una caja con overflow: auto u overflow: scroll) y los desplazamientos programáticos dentro de ese contenedor también se animarán. Consulta overflow para saber cómo se crean las cajas desplazables.
.panel {
height: 300px;
overflow-y: auto;
scroll-behavior: smooth;
}// Smoothly scrolls .panel to its bottom because the
// container has scroll-behavior: smooth.
const panel = document.querySelector('.panel');
panel.scrollTop = panel.scrollHeight;Relación con las APIs de desplazamiento de JavaScript
scroll-behavior es la forma CSS de establecer la animación predeterminada para un contenedor de desplazamiento. Las APIs de desplazamiento también pueden solicitar suavizado por llamada mediante una opción behavior, que anula el valor CSS para esa llamada concreta:
// One-off smooth scroll, regardless of the CSS scroll-behavior value.
element.scrollIntoView({ behavior: 'smooth' });
window.scrollTo({ top: 0, behavior: 'smooth' });Usa la propiedad CSS cuando quieras que cada salto de navegación/ancla en un contenedor sea suave; usa la opción de JS para un desplazamiento puntual y específico.
Accesibilidad
El desplazamiento suave puede causar molestias a los usuarios sensibles al movimiento. Respeta la media query prefers-reduced-motion para que la animación se deshabilite cuando el usuario haya pedido al sistema que reduzca el movimiento:
html {
scroll-behavior: smooth;
}
@media (prefers-reduced-motion: reduce) {
html {
scroll-behavior: auto;
}
}Propiedades relacionadas
- overflow — crea las cajas desplazables que
scroll-behavioranima. - scrollbar — aplica estilos a la barra de desplazamiento de esas cajas.
- offset-anchor — controla el punto de anclaje utilizado durante las transformaciones.
- HTML links — los anclas
href="#id"que activan el desplazamiento suave.