Estilo da barra de rolagem

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

Bramus

Introdução

Desde a versão 2 do Chrome, é possível estilizar 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.

O que foi padronizado são as propriedades scrollbar-width e scrollbar-color, parte da especificação do nível 1 do módulo de estilização de barras de rolagem do CSS. 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. À medida que você rola a tela, 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.

Sobrepor barras de rolagem

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 por baixo visível, eles geralmente são semitransparentes, mas isso depende do 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 do espaço do conteúdo adjacente.

Ilustração de um navegador com uma barra de rolagem clássica. A barra de rolagem fica posicionada ao lado do conteúdo na própria área dedicada. A largura disponível do conteúdo é reduzida em comparação com a largura disponível quando as barras de rolagem de sobreposição 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 <color> determina a cor do ícone, e o segundo, a cor da 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 de rolagem completamente sem afetar a capacidade de 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 marcador só é desenhado enquanto você rola a área de rolagem.

Demonstração: como estilizar 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