Propriedade CSS scroll-behavior
Use a propriedade CSS scroll-behavior para especificar o comportamento da rolagem. Veja os valores e exemplos da propriedade.
A propriedade CSS scroll-behavior define se uma rolagem acionada pela navegação ou por um script (uma "caixa de rolagem" que salta para uma âncora ou para uma coordenada) deve ser suave (animada) ou instantânea (um único salto). Por padrão, o valor é auto, o que significa um salto abrupto.
Esta página aborda o que a propriedade faz, onde você deve declará-la, a diferença entre seus valores, erros comuns e como ela se relaciona com as APIs de rolagem do JavaScript.
Quando devo usá-la?
O caso de uso mais comum é a navegação dentro da página. Quando um link aponta para um fragmento como <a href="#section">, o navegador normalmente salta instantaneamente para o destino. Definir scroll-behavior: smooth no contêiner de rolagem transforma esse salto em uma rolagem animada agradável — sem uma linha sequer de JavaScript.
html {
scroll-behavior: smooth;
}Onde declará-la
Dois pontos costumam confundir as pessoas:
- Ela afeta apenas rolagens programáticas e acionadas por navegação — clicar em uma âncora, chamar
element.scrollIntoView(),window.scrollTo(), etc. Não tem efeito sobre rolagens realizadas pelo usuário com a roda do mouse, trackpad ou barra de rolagem. - Para a rolagem do viewport, defina-a no
html, não nobody. O valor declarado no elemento body não se propaga para o viewport, portanto seria ignorado. Declare-a no elemento html (a caixa de rolagem raiz). Para qualquer outro contêiner rolável, declare-a no próprio contêiner.
Os agentes de usuário têm permissão para ignorar esta propriedade, e ela será ignorada para usuários que solicitam movimentos reduzidos (consulte Acessibilidade abaixo).
| Valor Inicial | auto |
|---|---|
| Aplica-se a | Caixas de rolagem. |
| Herdado | Não. |
| Animável | Não. |
| Versão | CSSOM View Module (Working Draft) |
| Sintaxe DOM | object.style.scrollBehavior = "smooth"; |
Sintaxe
Sintaxe CSS da scroll-behavior
scroll-behavior: auto | smooth | initial | inherit;Exemplo da propriedade scroll-behavior com o valor "auto":
Exemplo de código CSS com 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>Exemplo da propriedade scroll-behavior com o valor "smooth":
CSS scroll-behavior com valor smooth, exemplo
<!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>Com smooth, clicar em qualquer um dos links anima a página entre os dois blocos em vez de saltar instantaneamente. Apenas o valor de scroll-behavior difere do exemplo anterior.
Valores
| Valor | Descrição |
|---|---|
| auto | Padrão. A rolagem acontece em um único salto instantâneo, sem animação. |
| smooth | A rolagem é animada suavemente entre as posições inicial e final. |
| initial | Define a propriedade com seu valor padrão (auto). |
| inherit | Herda o valor do elemento pai. |
Suavizando um contêiner específico
scroll-behavior não se limita à página. Declare-a em qualquer elemento que tenha sua própria barra de rolagem (uma caixa com overflow: auto ou overflow: scroll) e as rolagens programáticas dentro desse contêiner também serão animadas. Veja overflow para entender como caixas roláveis são criadas.
.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;Relação com as APIs de rolagem do JavaScript
scroll-behavior é a forma CSS de definir a animação padrão para um contêiner de rolagem. As APIs de rolagem também podem solicitar suavização por chamada com uma opção behavior, que substitui o valor CSS para aquela chamada específica:
// One-off smooth scroll, regardless of the CSS scroll-behavior value.
element.scrollIntoView({ behavior: 'smooth' });
window.scrollTo({ top: 0, behavior: 'smooth' });Use a propriedade CSS quando quiser que cada salto de navegação/âncora em um contêiner seja suave; use a opção JS para uma rolagem pontual e ad-hoc.
Acessibilidade
A rolagem suave pode causar desconforto para usuários sensíveis a movimentos. Respeite a media query prefers-reduced-motion para que a animação seja desativada quando o usuário solicitar ao sistema que reduza os movimentos:
html {
scroll-behavior: smooth;
}
@media (prefers-reduced-motion: reduce) {
html {
scroll-behavior: auto;
}
}Propriedades relacionadas
- overflow — cria as caixas roláveis que
scroll-behavioranima. - scrollbar — estiliza a barra de rolagem dessas caixas.
- offset-anchor — controla o ponto de âncora usado durante as transformações.
- HTML links — as âncoras
href="#id"que acionam a rolagem suave.