CSS / list-style-image: imagens, tamanho e marcadores alternativos

CSS list-style-image especifica uma imagem para o marcador de um item de lista. É comumente definido em ul ou ol e herdado por seus itens li. Se nenhuma imagem utilizável estiver disponível, o marcador list-style-type é usado em vez disso, então defina também um marcador alternativo apropriado.

Função e valores de list-style-image

O valor inicial é none, e a propriedade é herdada. Marcadores pertencem a elementos com display: list-item, como elementos li comuns. Definir isso em ul geralmente funciona porque os itens da lista herdam o valor; esta propriedade não adiciona uma imagem de fundo ao próprio ul.

Na sintaxe, url() é uma função contendo uma URL, não a palavra simples url. O tipo de animação é discreto, o que não significa que duas imagens se transformem suavemente uma na outra. MDN list-style-image referência

Um exemplo completo para copiar

Salve o código completo abaixo como list-marker.html em UTF-8 e abra-o em um navegador. Nenhuma biblioteca, servidor ou arquivo de imagem separado é necessário. SVG, Scalable Vector Graphics, é um formato de imagem vetorial; este exemplo incorpora um círculo azul 16×16 em uma URL de dados. As palavras em inglês são itens de comparação.

<!doctype html>
<html lang="pt">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Comparar marcadores de imagem</title>
  <style>
    body { max-width: 42rem; margin: 0 auto; padding: 1rem; font-family: sans-serif; }
    h2 { font-size: 1.1rem; }
    .image-list {
      list-style-type: square;
      list-style-position: outside;
      list-style-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 16 16'%3E%3Ccircle cx='8' cy='8' r='6' fill='%230066cc'/%3E%3C/svg%3E");
      font-size: 20px;
      max-width: 22rem;
      padding-inline-start: 2rem;
    }
    .image-list li { margin-block: .5rem; }
    .large { font-size: 32px; }
    .reset { list-style-image: none; }
  </style>
</head>
<body>
  <h1>Comparar marcadores de imagem</h1>
  <h2>list-style-image</h2>
  <ul class="image-list"><li>Alpha</li><li>Beta Gamma Delta Epsilon Zeta Eta Theta Iota Kappa</li></ul>
  <h2>font-size: 32px</h2>
  <ul class="image-list large"><li>Alpha</li><li>Beta Gamma Delta Epsilon Zeta Eta Theta Iota Kappa</li></ul>
  <h2>list-style-image: none</h2>
  <ul class="image-list reset"><li>Alpha</li><li>Beta Gamma Delta Epsilon Zeta Eta Theta Iota Kappa</li></ul>
</body>
</html>

O resultado esperado é um marcador em círculo azul nas duas primeiras listas e marcadores quadrados na terceira. Apenas o texto cresce para 32px na segunda lista. Quando o segundo item longo quebrar a linha, compare o alinhamento de um marcador externo com seu texto. Depois de editar o arquivo, salve e recarregue.

Separar o tamanho da imagem e o da fonte

Este SVG especifica explicitamente largura e altura como 16, dando ao marcador de imagem dimensões de 16×16 pixels CSS. Aumentar o texto de 20px para 32px não amplia automaticamente esta imagem proporcionalmente. Também é impreciso dizer que toda imagem de marcador sempre usa suas dimensões de pixel originais: o tamanho pode diferir quando uma imagem não tem dimensões intrínsecas ou proporção.

list-style-image não possui parâmetros separados de largura ou altura para marcador. Prepare um pequeno recurso de marcador ou dê ao SVG dimensões apropriadas. As propriedades suportadas por ::marker também são limitadas; definir largura e altura lá não fornece dimensionamento arbitrário de imagem. Para tamanho e espaçamento precisos, considere um design separado de background-image ou pseudo-elemento, preservando a semântica da lista e a informação real do texto. MDN: propriedades permitidas em ::marker

Remover imagens e verificar a notação abreviada

Para remover apenas a imagem, defina list-style-image: none como abaixo. O exemplo mantém list-style-type: square, então os marcadores quadrados aparecem. Compare a alteração e restaure a declaração original url() para trazer a imagem de volta. O marcador alternativo também é usado quando o carregamento da imagem falha e nenhuma imagem utilizável está disponível.

.image-list {
  list-style-image: none;
}

A seguinte notação abreviada list-style redefine também o componente de imagem omitido. Aplicá-lo mais tarde pode, portanto, remover uma imagem declarada anteriormente. Verifique se há uma sobrescrita posterior por uma notação abreviada e use propriedades individuais ou inclua a imagem na notação abreviada de acordo com sua intenção.

.image-list {
  list-style: square outside;
}

Investigar marcadores que não aparecem

1. Verifique a URL da imagem e a resposta. Uma URL relativa em uma folha de estilo externa é resolvida em relação a esse arquivo CSS, não ao arquivo HTML. Uma URL em um elemento style segue a URL base do documento. Use o painel de Rede nas ferramentas de desenvolvedor para verificar respostas 404 e formatos de imagem inválidos.
2. Inspecione o item de lista (li) selecionado, verificando a propriedade list-style-image computada e o display. Verifique se há uma declaração abreviada de list-style ou uma regra de prioridade mais alta que sobrescreve o valor. Também verifique se o display foi alterado para algo como flex, de modo que o elemento não gere mais um marcador de item de lista.
3. Com posicionamento externo, indentação insuficiente ou a configuração de overflow de um elemento pai podem cortar o marcador. Verifique o padding da lista e o corte (clipping). Se a política do site bloquear URLs de dados, substitua a imagem de exemplo por uma URL de imagem permitida.

Listas aninhadas também podem herdar essa propriedade. Para remover imagens de uma lista aninhada, aplique explicitamente list-style-image: none a essa lista e defina seu list-style-type para o valor desejado.

Preservar o significado e a acessibilidade da lista

O círculo azul aqui é decorativo. Coloque significados importantes, como conclusão, avisos ou classificações, no texto real do item da lista, em vez de apenas em uma imagem CSS. Os marcadores CSS não fornecem um atributo alt como o de um elemento img do HTML, então não omita informações assumindo que a imagem será carregada ou anunciada.

Dar a um ol o mesmo marcador de imagem substitui seus números visíveis por imagens. Mantenha os números nativos quando os leitores precisarem de numeração de passos. Preserve a estrutura ul, ol e li, e verifique se os itens e sua sequência permanecem compreensíveis sem imagens. W3C definição de marcadores de lista com imagens