Estilo da barra de rolagem

Use as propriedades scrollbar-width e scrollbar-color para definir o estilo das barras de rolagem.

Introdução

A partir do Chrome versão 2, é possível estilizar as barras de rolagem com os pseudoelementos ::-webkit-scrollbar-*. Essa abordagem funciona bem no Chrome e no Safari, mas nunca foi padronizada pelo CSS Working Group.

Os padrões foram as propriedades scrollbar-width e scrollbar-color, que fazem parte da especificação do módulo de estilo das barras de rolagem do CSS nível 1 (em inglês). Essas propriedades têm suporte a partir do Chrome 121.

Compatibilidade com navegadores

  • Chrome: 121
  • Borda: 121.
  • Firefox: 64.
  • Safari: incompatível.

Origem

Barras de rolagem 101

Anatomia de uma barra de rolagem

No mínimo, uma barra de rolagem consiste em uma faixa e um círculo. A trilha é a área em que o polegar pode se mover. A faixa representa toda a distância de rolagem. O círculo representa a posição atual na região rolável. Conforme você rola, ele se move dentro da faixa. Muitas vezes, o polegar também é arrastável.

No entanto, as barras de rolagem podem ter mais partes do que apenas o círculo e a faixa. Por exemplo, uma barra de rolagem pode ter um ou mais botões para incrementar ou diminuir o deslocamento de rolagem. As partes que compõem uma barra de rolagem são determinadas pelo sistema operacional.

Ilustração das partes que compõem uma barra de rolagem.
Ilustração das partes que compõem uma barra de rolagem. A ilustração à esquerda é uma barra de rolagem mínima com apenas uma faixa e um círculo. O da direita também tem botões.

Barras de rolagem clássicas e de sobreposição

Antes de ver como definir o estilo das barras de rolagem, é importante entender a diferença entre dois tipos de barra de rolagem.

Barras de rolagem de sobreposição

As barras de rolagem de sobreposição são barras de rolagem flutuantes renderizadas sobre o conteúdo abaixo. Eles não são mostrados por padrão, mas apenas enquanto você está rolando a tela. Para manter o conteúdo abaixo visível, eles geralmente são semitransparentes, mas isso cabe ao sistema operacional. Ao interagir com eles, o tamanho deles também pode variar.

Ilustração de um navegador com uma barra de rolagem sobreposta.
Ilustração de um navegador com uma barra de rolagem sobreposta. A barra de rolagem se sobrepõe ao conteúdo. o polegar fica parcialmente transparente.

Barras de rolagem clássicas

As barras de rolagem clássicas são aquelas colocadas em um gutter de barra de rolagem dedicado. A medianiz da barra de rolagem é o espaço entre a borda interna e a borda de padding externa. Essas barras de rolagem geralmente são opacas (não transparentes) e ocupam um pouco de espaço do conteúdo adjacente.

Ilustração de um navegador com uma barra de rolagem clássica.
Ilustração de um navegador com uma barra de rolagem clássica. A barra de rolagem é posicionada ao lado do conteúdo em uma área própria dedicada. a largura disponível do conteúdo é reduzida em comparação com a largura disponível quando barras de rolagem de sobreposição são usadas.

Propriedades scrollbar-color e scrollbar-width.

Usar scrollbar-color para dar cor às barras de rolagem

A propriedade scrollbar-color permite mudar o esquema de cores das barras de rolagem. A propriedade aceita dois valores <color>. O primeiro valor de <color> determina a cor do polegar, e o segundo determina a cor a ser usada na faixa.

.scroller {
  scrollbar-color: hotpink blue;
}

Ao usar uma barra de rolagem de sobreposição, a cor da faixa não tem efeito por padrão. No entanto, ao passar o cursor sobre a barra de rolagem, a faixa será exibida.

Demonstração: como definir o estilo de barras de rolagem: scrollbar-color

Para usar a renderização padrão fornecida pelo sistema operacional, use auto como o valor.

Como mudar o tamanho da barra de rolagem com scrollbar-width

A propriedade scrollbar-width permite escolher uma barra de rolagem mais estreita ou até mesmo ocultar a barra completamente sem afetar a rolagem.

Os valores aceitos são auto, thin e none.

  • auto: a largura padrão da barra de rolagem, conforme fornecido pela plataforma.
  • thin: uma variante fina da barra de rolagem fornecida pela plataforma ou uma barra de rolagem personalizada mais fina que a barra de rolagem padrão da plataforma.
  • none: oculta a barra de rolagem. No entanto, o elemento ainda pode ser rolável.

Não é possível usar um <length> como 16px como o valor de scrollbar-width.

.scroller {
  scrollbar-width: thin;
}

Ao usar uma barra de rolagem de sobreposição, o polegar só é desenhado enquanto você rola ativamente a área de rolagem.

Demonstração: como definir o estilo de barras de rolagem: scrollbar-width

Compatibilidade com versões mais antigas de navegadores

Para atender a versões de navegadores que não são compatíveis com scrollbar-color e scrollbar-width, é possível usar as novas propriedades scrollbar-* e ::-webkit-scrollbar-*.

.scroller {
    --scrollbar-color-thumb: hotpink;
    --scrollbar-color-track: blue;
    --scrollbar-width: thin;
    --scrollbar-width-legacy: 10px;
}

/* Modern browsers with `scrollbar-*` support */
@supports (scrollbar-width: auto) {
    .scroller {
        scrollbar-color: var(--scrollbar-color-thumb) var(--scrollbar-color-track);
        scrollbar-width: var(--scrollbar-width);
    }
}

/* Legacy browsers with `::-webkit-scrollbar-*` support */
@supports selector(::-webkit-scrollbar) {
    .scroller::-webkit-scrollbar-thumb {
        background: var(--scrollbar-color-thumb);
    }
    .scroller::-webkit-scrollbar-track {
        background: var(--scrollbar-color-track);
    }
    .scroller::-webkit-scrollbar {
        max-width: var(--scrollbar-width-legacy);
        max-height: var(--scrollbar-width-legacy);
    }
}
Demonstração: como definir o estilo de barras de rolagem usando scrollbar-* com um substituto para ::-webkit-scrollbar-*

Quando você define width ou height de ::-webkit-scrollbar, uma barra de rolagem de sobreposição sempre é mostrada, transformando-a em uma barra de rolagem clássica.

Para manter a ilusão, você pode escolher mudar as cores apenas ao passar o cursor sobre o botão.

.scroller::-webkit-scrollbar-thumb {
    background: transparent;
}
.scroller::-webkit-scrollbar-track {
    background: transparent;
}
.scroller:hover::-webkit-scrollbar-thumb {
    background: var(--scrollbar-color-thumb);
}
.scroller:hover::-webkit-scrollbar-track {
    background: var(--scrollbar-color-track);
}

.scroller:hover {
    --fix: ; /* This custom property invalidates styles on hover, thereby enforcing a style recomputation. This is needed to work around a bug in Safari. */
}
Demonstração: como definir o estilo de barras de rolagem usando scrollbar-* com um substituto para ::-webkit-scrollbar-*, aplicando somente as cores ::-webkit-scrollbar-* ao passar o cursor