Estilização de Barras de Rolagem CSS — Referência Completa
As barras de rolagem do navegador são um dos elementos de interface padrão mais consistentemente feios na web, e variam drasticamente entre sistemas operacionais. No Windows aparecem como barras cinzas largas que ocupam espaço de layout mesmo quando não estão em uso. No macOS são estreitas e só aparecem durante a rolagem. A estilização CSS de barras de rolagem permite que você substitua esses padrões para criar barras que correspondam ao seu sistema de design — ou para ocultá-las completamente mantendo o conteúdo rolável.
Duas APIs concorrentes que você deve conhecer
Existem atualmente duas especificações CSS separadas para estilização de barras de rolagem. A API de pseudo-elementos WebKit usa uma família de pseudo-elementos ::-webkit-scrollbar e funciona no Chrome, Edge e Safari. A especificação W3C CSS Scrollbars Level 1 usa as propriedades scrollbar-color e scrollbar-width — o Firefox a suporta desde a versão 64, e o Chrome e Edge a adotaram a partir da versão 121. A abordagem correta para código de produção é incluir ambas.
A família de pseudo-elementos WebKit
A abordagem WebKit funciona expondo os sub-componentes da barra de rolagem como pseudo-elementos estilizáveis. O pseudo-elemento ::-webkit-scrollbar aponta para a barra completa. ::-webkit-scrollbar-thumb estiliza o controle arrastável. ::-webkit-scrollbar-track estiliza a área da trilha atrás do thumb. Para que o estilizado WebKit se aplique a um elemento, esse elemento deve ter uma barra de rolagem — precisa de overflow: auto ou overflow: scroll e conteúdo que exceda suas dimensões.
A propriedade W3C scrollbar-color
A propriedade scrollbar-color recebe exatamente dois valores de cor: a cor do thumb primeiro, depois a cor da trilha. Não aceita gradientes e você não pode controlar estados hover ou border-radius. O que falta em controle compensa em simplicidade e conformidade com padrões.
A propriedade scrollbar-width
auto usa o padrão da plataforma. thin produz uma barra de rolagem mais estreita, aproximadamente 8px na maioria das implementações. none oculta a barra de rolagem completamente mantendo o conteúdo rolável — o elemento ainda responde a eventos de roda do mouse, teclado e touch, mas nenhuma barra visível aparece.
Escopo de estilos de barra de rolagem
Estilos de barra de rolagem declarados sem seletor de escopo se aplicam globalmente a todos os elementos roláveis da página. Para escopar um estilo a um elemento específico, prefixe o seletor do elemento ao pseudo-elemento: .code-block::-webkit-scrollbar { width: 4px; }.
Estilização de barra de rolagem horizontal
Barras de rolagem horizontais usam height em vez de width no pseudo-elemento ::-webkit-scrollbar. Todo o resto funciona de forma idêntica às barras de rolagem verticais.
Projetando barras de rolagem para acessibilidade
A consideração de acessibilidade mais importante é a visibilidade e o tamanho da barra de rolagem. Barras de rolagem muito estreitas — 2-3px de largura — podem ser quase invisíveis e difíceis de agarrar com o mouse, especialmente para usuários com deficiências motoras. O critério de sucesso 2.5.5 do WCAG 2.1 recomenda que alvos interativos tenham pelo menos 44×44 pixels CSS.
Comportamento no macOS vs Windows
O macOS oculta barras de rolagem por padrão e as mostra como sobreposição apenas durante a rolagem ativa. Isso significa que a barra de rolagem não ocupa espaço de layout. No Windows, a barra de rolagem ocupa espaço de layout permanente ao lado do conteúdo. Use scrollbar-gutter: stable para reservar espaço de layout para a barra no macOS.
Comportamento de barras de rolagem em móveis
O iOS Safari e o Android Chrome tratam barras de rolagem como sobreposições que aparecem brevemente durante a rolagem e depois desaparecem. O CSS personalizado de barras de rolagem essencialmente não tem efeito em móveis.
Usando variáveis CSS para barras de rolagem temáticas
Uma das aplicações mais práticas de barras de rolagem personalizadas é integrá-las nos tokens de tema de um sistema de design. Usando propriedades CSS personalizadas para as cores do thumb e da trilha, você obtém alternância automática entre modo escuro e claro sem JavaScript.
As barras de rolagem personalizadas funcionam no Firefox?
O Firefox suporta as propriedades scrollbar-color e scrollbar-width desde a versão 64. Ele não suporta os pseudo-elementos ::-webkit-scrollbar. Para cobertura do Firefox, sempre inclua ambas as APIs.
Por que meu estilo ::-webkit-scrollbar não funciona?
O elemento deve ter uma barra de rolagem para estilizá-la. Verifique se o elemento tem overflow: auto ou overflow: scroll e se o conteúdo realmente excede as dimensões do elemento.
Posso usar gradientes com scrollbar-color?
Não — scrollbar-color aceita apenas dois valores de cor sólida. Gradientes são possíveis apenas via ::-webkit-scrollbar-thumb { background: linear-gradient(...) } em navegadores WebKit.
O que é scrollbar-gutter e quando devo usá-lo?
scrollbar-gutter controla se o espaço de layout é reservado para a barra de rolagem mesmo quando não está visível. O valor stable reserva o espaço permanentemente, prevenindo deslocamentos de layout quando o conteúdo muda.