Estilo da barra de rolagem

Use as propriedades scrollbar-width e scrollbar-color para estilizar barras de rolagem.

Bramus

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 Grupo de Trabalho do CSS.

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

• 121
• 121
• 64
• x

Origem

Noções básicas sobre barras de rolagem

Anatomia de uma barra de rolagem

No mínimo, uma barra de rolagem consiste em uma faixa e um botão de rolagem. A faixa é a área em que o polegar pode se mover. A faixa representa toda a distância de rolagem. O ícone 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 pode ser arrastado.

As barras de rolagem podem ter mais partes do que apenas o botão e a faixa. Por exemplo, uma barra de rolagem pode ter um ou mais botões para incrementar ou decrementar o deslocamento. 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. A ilustração à esquerda é uma barra de rolagem mínima com apenas uma faixa e um círculo. A da direita também tem botões.

Barras de rolagem clássicas e sobrepostas

Antes de saber como estilizar barras de rolagem, é importante entender a diferença entre dois tipos delas.

Barras de rolagem de sobreposição

As barras de rolagem sobrepostas são barras de rolagem flutuantes renderizadas sobre o conteúdo abaixo. Elas não são mostradas por padrão, mas apenas enquanto você rola a tela. Para manter o conteúdo abaixo visível, eles geralmente são semitransparentes, mas isso cabe ao sistema operacional. Durante a interação, o tamanho deles também pode variar.

Ilustração de um navegador com uma barra de rolagem de sobreposição. A barra de rolagem sobrepõe o conteúdo, e o ícone fica parcialmente transparente.

Barras de rolagem clássicas

As barras de rolagem clássicas são colocadas em um gutter dedicado. O gutter da barra de rolagem é o espaço entre a borda interna da borda e a borda externa do padding. 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. 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 sobrepostas são usadas.

As propriedades scrollbar-color e scrollbar-width

Como dar cor às barras de rolagem com scrollbar-color

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 vai aparecer.

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

Para usar a renderização padrão fornecida pelo sistema operacional, use auto como 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 da barra de rolagem padrão fornecida pela plataforma.
• thin: uma variante fina da barra de rolagem fornecida pela plataforma ou uma barra de rolagem personalizada mais fina do que a padrão da plataforma.
• none: oculta a barra de rolagem. No entanto, o elemento ainda pode ser rolado.

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 ponteiro só é desenhado enquanto você rola ativamente a área rolável.

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

Suporte a versões mais antigas do navegador

Para atender às versões de navegador que não oferecem suporte a 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 estilizar barras de rolagem usando scrollbar-* com um substituto para ::-webkit-scrollbar-*

Quando você define o width ou o 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 controle deslizante.

.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 estilizar barras de rolagem usando scrollbar-* com um substituto para ::-webkit-scrollbar-*, aplicando apenas as cores de ::-webkit-scrollbar-* ao passar o cursor