Propriedade CSS counter-reset

A propriedade counter-reset cria um ou mais contadores CSS e define um valor inicial para cada um deles. Apesar do nome, sua principal função é inicializar um contador para que possa ser usado posteriormente — ela não apenas zera um contador existente, mas o traz à existência no escopo atual.

Contadores CSS são variáveis mantidas pelo navegador cujos valores podem ser incrementados por regras CSS para rastrear quantas vezes são usados. Eles tornam possível numerar seções, capítulos, itens de lista ou qualquer elemento repetido inteiramente em CSS, sem alterações de marcação ou JavaScript.

Um contador só é útil como parte de um trio de propriedades:

counter-reset — cria o contador e define seu valor inicial (esta página).
counter-increment — adiciona ao valor do contador, geralmente uma vez por elemento correspondente.
content — exibe o valor do contador através da função counter() ou counters(), tipicamente dentro de um pseudo-elemento ::before.

Esta página aborda a sintaxe de counter-reset, como funciona o escopo de contadores, numeração de seções aninhadas, uso de valores iniciais negativos e personalizados, e os valores que a propriedade aceita.

Como funciona

Cada declaração de counter-reset recebe um nome de contador que você inventa (por exemplo, section) seguido de um inteiro opcional como valor inicial:

/* "section" counter created, starts at 0 */
counter-reset: section;

/* "section" counter created, starts at 5 */
counter-reset: section 5;

/* multiple counters in one declaration */
counter-reset: chapter 0 page 1;

Se você omitir o número, o contador começa em 0. O primeiro elemento correspondente então executa counter-increment antes que content o leia, portanto um contador que começa em 0 e incrementa em 1 exibe 1 no primeiro elemento — que é geralmente o que você deseja.

O escopo importa. Um contador criado com counter-reset tem escopo no elemento em que é declarado e nos descendentes e irmãos seguintes desse elemento. É isso que permite redefinir um sub-contador para cada seção: colocar counter-reset: subsection em cada h2 dá a cada seção seu próprio contador subsection novo. O exemplo de numeração aninhada abaixo depende desse comportamento.

Valor Inicial	none
Aplicável a	Todos os elementos.
Herdado	Não.
Animável	Não.
Versão	CSS2
Sintaxe DOM	object.style.counterReset = "section" ;

Sintaxe

counter-reset: none | name number | initial | inherit;

O name é um identificador que você escolhe, e number é um inteiro opcional (pode ser negativo). Você pode listar vários pares name number em uma declaração para criar múltiplos contadores de uma vez.

Exemplo: definindo um contador com JavaScript

counter-reset também é acessível a partir do DOM como element.style.counterReset. Clique em "Try it" para redefinir o contador section para 5, fazendo com que os títulos sejam renumerados a partir de 6.

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
    <style>
      h2::before {
        counter-increment: section;
        content: "Book " counter(section) ". ";
      }
    </style>
  </head>
  <body>
    <p>Click the "Try it" button to set the counter-reset property:</p>
    <button onclick="myFunction()">Try it</button>
    <h2>HTML Tutorials</h2>
    <h2>JavaScript Tutorials</h2>
    <h2>CSS Tutorials</h2>
    <script>
      function myFunction() {
        document.body.style.counterReset = "section 5";
      }
    </script>
  </body>
</html>

Experimente Você Mesmo »

Exemplo com incremento negativo (contagem regressiva)

Números negativos são permitidos tanto como valores iniciais quanto em counter-increment. Aqui o contador é criado em 0 e o incremento é -1, portanto cada título conta para baixo: -1, -2, -3, -4.

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
    <style>
      body {
        /* create "my-counter", start at 0 */
        counter-reset: my-counter;
      }
      h2::before {
        /* decrease "my-counter" by 1 on each h2 */
        counter-increment: my-counter -1;
        content: "Section " counter(my-counter) ". ";
      }
    </style>
  </head>
  <body>
    <h2>HTML Tutorial</h2>
    <h2>CSS Tutorial</h2>
    <h2>JavaScript Tutorial</h2>
    <h2>PHP Tutorial</h2>
  </body>
</html>

Experimente Você Mesmo »

Exemplo com seções e subseções numeradas

Este é o uso mais comum no mundo real de counter-reset: numeração aninhada como 1.1, 1.2, 2.1. O contador subsection é redefinido em cada h2, para que cada seção reinicie sua numeração de subseção a partir de 1. Sem essa redefinição por h2, as subseções continuariam crescendo ao longo de todo o documento.

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
    <style>
      body {
        /* Set "section" to 0 */
        counter-reset: section;
      }
      h2 {
        /* Set "subsection" to 0 */
        counter-reset: subsection;
      }
      h2::before {
        counter-increment: section;
        content: "Book " counter(section) ": ";
      }
      h3::before {
        counter-increment: subsection;
        content: counter(section) "." counter(subsection) " ";
      }
    </style>
  </head>
  <body>
    <h2>HTML</h2>
    <h3>HTML Basics</h3>
    <h3>HTML Templates</h3>
    <h3>HTML References</h3>
    <h3>HTML Tags</h3>
    <h2>CSS</h2>
    <h3>CSS Basics</h3>
    <h3>CSS References</h3>
    <h3>CSS Advanced</h3>
    <h3>CSS Guides</h3>
    <h3>CSS Selectors</h3>
    <h3>CSS Properties</h3>
  </body>
</html>

Experimente Você Mesmo »

Valores

Valor	Descrição
none	Os contadores não são incrementados.
name number	Name define o nome do contador a ser redefinido. Number define o valor para o qual o contador será redefinido a cada ocorrência do elemento. O padrão é 0 se não especificado.
initial	Define a propriedade para seu valor padrão.
inherit	Herda a propriedade do seu elemento pai.

Problemas comuns

Nada aparece sozinho. counter-reset apenas cria o contador. Você ainda precisa de counter-increment para avançá-lo e de content: counter(name) para exibi-lo. Uma página com apenas counter-reset não renderiza números.
counter-reset vs counter-set. counter-reset cria um contador no escopo atual; o mais recente counter-set apenas altera o valor de um contador que já existe e nunca cria um novo escopo. Use counter-reset quando quiser que a numeração recomece dentro de uma seção.
O incremento ocorre antes da exibição. Como o incremento em um ::before acontece antes que content seja lido, um contador começando em 0 com +1 exibe 1 no primeiro elemento. Comece em um valor diferente se precisar de um primeiro número diferente.
Contadores não são herdados. O valor da propriedade não é herdado, mas o contador em si é visível para descendentes e irmãos seguintes através do escopo — é isso que faz a numeração aninhada funcionar.

Suporte dos navegadores

counter-reset faz parte do CSS2 e é suportado em todos os navegadores modernos, incluindo Chrome, Firefox, Safari, Edge e Opera.

Prática

Para que serve a propriedade CSS 'counter-reset'?

É usada para evitar a recorrência de um elemento.Ela cria ou redefine contadores CSS em uma lista ou qualquer outro elemento.Ela estiliza a cor de fundo de um elemento.Ela adiciona uma imagem ou gradiente a um elemento HTML.Ela posiciona elementos como 'fixed', 'relative' ou 'absolute'.É frequentemente usada com a propriedade 'counter-increment' e a propriedade 'content'.