Propriedade CSS list-style-image

A propriedade CSS list-style-image substitui o marcador padrão de item de lista (o disco, círculo ou número) por uma imagem de sua escolha. É a maneira mais simples de dar marcadores personalizados a um <ol> ou <ul> — um checkmark, uma seta, um ícone — sem adicionar marcação extra.

Esta página abrange o que a propriedade faz, os valores que aceita, como o marcador é dimensionado, problemas comuns e como ela se encaixa na abreviação list-style.

Quando usar

Use list-style-image quando quiser marcadores decorativos provenientes de uma imagem pequena e única e não precisar controlar o tamanho ou espaçamento exato do marcador. Se precisar de controle preciso sobre o marcador (tamanho, espaçamento, alinhamento), a abordagem moderna é usar o pseudo-elemento ::marker ou um background-image em cada <li> com padding-left — list-style-image não oferece nenhuma forma de redimensionar a imagem, então um gráfico muito grande irá dominar a linha.

Como o marcador é dimensionado

Se a imagem tiver largura e altura intrínsecas, elas são usadas diretamente como tamanho do marcador. Se a imagem tiver uma proporção intrínseca mais apenas uma dimensão intrínseca, a dimensão ausente é calculada a partir da proporção. Como não há CSS para escalar o marcador, prepare a imagem no tamanho em que deseja que ela apareça (tipicamente 16×16 ou menor).

A propriedade list-style-image se aplica a itens de lista e a qualquer elemento com display definido como list-item. Por padrão isso significa elementos <li>, mas você também pode defini-la no elemento pai <ol> ou <ul>, onde ela é herdada pelos itens de lista.

Informação

Se a imagem não carregar, o marcador recorre ao valor de list-style-type (um disco por padrão). Mantenha sempre um list-style-type adequado para que imagens quebradas não deixem sua lista sem marcadores.

Valor inicial	none
Aplica-se a	Itens de lista.
Herdada	Sim.
Animável	Não.
Versão	CSS1
Sintaxe DOM	object.style.listStyleImage = 'url("image.jpg")';

Sintaxe

Sintaxe da propriedade CSS list-style-image

list-style-image: none | <url> | image-set() | initial | inherit;

Exemplo da propriedade list-style-image:

Exemplo da propriedade CSS list-style-image com valor none

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
    <style>
      ul {
        list-style-image: none;
      }
    </style>
  </head>
  <body>
    <h2>List-style-image property example</h2>
    <ul>
      <li>List item 1</li>
      <li>List item 2</li>
      <li>List item 3</li>
    </ul>
  </body>
</html>

Experimente Você Mesmo »

Resultado

![Propriedade CSS list-style-image](/uploads/media/default/0001/04/3253cd4b1e6f2bdbce6333da58573f6d8a9a0d53.png "CSS list-style-image none result" =420x)

Exemplo da propriedade list-style-image com URL de origem da imagem:

Exemplo da propriedade CSS list-style-image

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
    <style>
      ul {
        list-style-image: url("/uploads/media/default/0001/01/03d3f916bd5c266dd5008d5c210478cc730437eb.png");
      }
    </style>
  </head>
  <body>
    <h2>List-style-image property example</h2>
    <ul>
      <li>List item 1</li>
      <li>List item 2</li>
      <li>List item 3</li>
    </ul>
  </body>
</html>

Experimente Você Mesmo »

Usando a abreviação list-style

Na prática, a imagem é geralmente definida em conjunto com o tipo e a posição do marcador por meio da abreviação list-style. As duas regras abaixo são equivalentes:

/* Longhand */
ul {
  list-style-type: square;
  list-style-position: inside;
  list-style-image: url("arrow.png");
}

/* Shorthand — type, position, image in any order */
ul {
  list-style: square inside url("arrow.png");
}

O square aqui é o marcador de fallback usado enquanto a imagem carrega ou se ela estiver indisponível. Veja list-style-position para entender a diferença entre inside e outside.

Valores

Valor	Descrição	Experimente
`none`	Nenhuma imagem é exibida. O marcador definido por list-style-type é usado em vez disso. Este é o valor padrão.	Experimente »
`<url>`	A URL de origem da imagem a ser usada como marcador de item de lista, escrita como `url("path/to/image.png")`.	Experimente »
`image-set()`	Um conjunto de candidatos de imagem entre os quais o navegador escolhe com base no ambiente de renderização, por exemplo, a resolução da tela. Permite servir uma imagem mais nítida para telas de alta densidade de pixels.	Experimente »
`initial`	Redefine a propriedade para seu valor padrão (`none`).	Experimente »
`inherit`	Herda o valor do elemento pai.

Suporte a navegadores e acessibilidade

list-style-image é suportada em todos os navegadores modernos (remonta ao CSS1). Dois pontos a ter em mente:

A imagem é puramente decorativa — leitores de tela não a anunciam e não há texto alt. Não codifique significado no marcador que não esteja também presente no texto da lista.
A cor do marcador segue a color do texto para list-style-type, mas uma imagem mantém suas próprias cores. Se quiser que o marcador corresponda à cor do texto, use a abordagem ::marker ou background-image.

Prática

Qual é a função da propriedade 'list-style-image' no CSS?

Permite definir uma imagem como marcador de lista.Permite alterar a cor dos itens de lista.Controla o tamanho dos itens de lista.É usada para especificar a imagem a ser utilizada como marcador de item de lista.