Propiedad CSS list-style-image

La propiedad CSS list-style-image reemplaza el marcador predeterminado del elemento de lista (el disco, el círculo o el número) por una imagen de tu elección. Es la forma más sencilla de añadir viñetas personalizadas — una marca de verificación, una flecha, un icono — a un <ol> o <ul> sin agregar marcado adicional.

Esta página explica qué hace la propiedad, los valores que acepta, cómo se dimensiona el marcador, errores comunes y cómo encaja en la propiedad abreviada list-style.

Cuándo usarla

Recurre a list-style-image cuando quieras viñetas decorativas que provienen de una imagen pequeña y única, y no necesites controlar con precisión el tamaño o el espaciado de la viñeta. Si necesitas un control preciso sobre el marcador (tamaño, separación, alineación), el enfoque moderno es usar el pseudoelemento ::marker o un background-image en cada <li> con padding-left — list-style-image no ofrece ninguna forma de redimensionar la imagen, por lo que un gráfico demasiado grande dominará la línea.

Cómo se dimensiona el marcador

Si la imagen tiene un ancho y alto intrínsecos, se usan directamente como tamaño del marcador. Si la imagen tiene una relación de aspecto intrínseca más solo una dimensión intrínseca, la dimensión faltante se calcula a partir de la relación. Como no hay CSS para escalar el marcador, prepara la imagen al tamaño en que deseas que aparezca (normalmente 16×16 o menor).

La propiedad list-style-image se aplica a los elementos de lista y a cualquier elemento con display establecido en list-item. Por defecto, eso significa elementos <li>, pero también puedes establecerla en el elemento padre <ol> o <ul>, donde los elementos de lista la heredan.

Información

Si la imagen no se carga, el marcador recurre al valor de list-style-type (un disco por defecto). Mantén siempre un list-style-type adecuado para que las imágenes rotas no dejen tu lista sin viñetas.

Valor inicial	none
Se aplica a	Elementos de lista.
Heredable	Sí.
Animatable	No.
Versión	CSS1
Sintaxis DOM	object.style.listStyleImage = 'url("image.jpg")';

Sintaxis

Sintaxis de la propiedad CSS list-style-image

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

Ejemplo de la propiedad list-style-image:

Ejemplo de la propiedad CSS list-style-image con el 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>

Pruébalo tú mismo »

Resultado

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

Ejemplo de la propiedad list-style-image con una URL de imagen como fuente:

Ejemplo de la propiedad 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>

Pruébalo tú mismo »

Uso de la propiedad abreviada list-style

En la práctica, la imagen suele establecerse junto con el tipo de marcador y la posición mediante la propiedad abreviada list-style. Las dos reglas siguientes son 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");
}

El valor square aquí es el marcador de reserva que se usa mientras la imagen se carga o si no está disponible. Consulta list-style-position para ver la diferencia entre inside y outside.

Valores

Valor	Descripción	Pruébalo
`none`	No se muestra ninguna imagen. En su lugar se usa el marcador definido por list-style-type. Este es el valor predeterminado.	Pruébalo »
`<url>`	La URL de origen de la imagen que se usará como marcador del elemento de lista, escrita como `url("path/to/image.png")`.	Pruébalo »
`image-set()`	Un conjunto de candidatos de imagen entre los que el navegador elige en función del entorno de renderizado, por ejemplo, la resolución de pantalla. Permite servir una imagen más nítida en pantallas de alta densidad de píxeles.	Pruébalo »
`initial`	Restablece la propiedad a su valor predeterminado (`none`).	Pruébalo »
`inherit`	Hereda el valor del elemento padre.

Compatibilidad con navegadores y accesibilidad

list-style-image es compatible con todos los navegadores modernos (existe desde CSS1). Dos cosas a tener en cuenta:

La imagen es puramente decorativa — los lectores de pantalla no la anuncian y no hay texto alt. No codifiques significado en la viñeta que no esté también presente en el texto de la lista.
El color del marcador sigue el color del texto para list-style-type, pero una imagen conserva sus propios colores. Si quieres que la viñeta coincida con el color del texto, usa en cambio un enfoque con ::marker o background-image.

Práctica

¿Cuál es la función de la propiedad 'list-style-image' en CSS?

Permite establecer una imagen como marcador de viñeta para listas.Permite cambiar el color de los elementos de la lista.Controla el tamaño de los elementos de la lista.Se utiliza para especificar la imagen que se usará como marcador de elemento de lista.