CSS / list-style-image: image markers, sizing and fallback

CSS list-style-image specifies an image for a list item’s marker. It is commonly set on ul or ol and inherited by their li items. If no usable image is available, the list-style-type marker is used instead, so define an appropriate fallback too.

What list-style-image does and which values to use

The initial value is none, and the property is inherited. Markers belong to elements with display: list-item, such as ordinary li elements. Setting it on ul usually works because the list items inherit the value; this property does not add a background image to ul itself.

In the syntax, url() is a function containing a URL, not the bare word url. The animation type is discrete, which does not mean that two images smoothly morph into one another. MDN list-style-image reference

A complete example to copy and open

Save the complete code below as list-marker.html in UTF-8 and open it in a browser. No library, server or separate image file is needed. SVG, Scalable Vector Graphics, is a vector image format; this example embeds a 16×16 blue circle in a data URL. The English words are comparison items.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Compare image list markers</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>Compare image list markers</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>

The expected result is a blue circle marker in the first two lists and square markers in the third. Only the text grows to 32px in the second list. When the long second item wraps, compare the alignment of an outside marker with its text. After editing the file, save and reload.

Treat image size separately from font size

This SVG explicitly specifies width and height as 16, giving the image marker dimensions of 16 CSS pixels. Increasing the text from 20px to 32px does not automatically enlarge this image in proportion. It is also inaccurate to say that every marker image always uses its original pixel dimensions: sizing can differ when an image has no intrinsic dimensions or ratio.

list-style-image has no separate marker width or height parameter. Prepare a small marker asset or give the SVG appropriate dimensions. The properties supported by ::marker are limited too; setting width and height there does not provide arbitrary image sizing. For precise size and spacing, consider a separate background-image or pseudo-element design while preserving list semantics and actual text information. MDN properties supported by ::marker

Remove images and watch for shorthand resets

To remove only the image, set list-style-image: none as below. The example retains list-style-type: square, so square markers appear. Compare the change and restore the original url() declaration to bring back the image. The fallback marker is also used when image loading fails and no usable image is available.

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

The following list-style shorthand resets the omitted image component too. Applying it later can therefore remove an image declared earlier. Check for a later shorthand override, and use individual properties or include the image in the shorthand according to your intention.

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

Check missing list markers

1. Check the image URL and response. A relative URL in an external stylesheet is resolved relative to that CSS file, not the HTML file. A URL in a style element follows the document’s base URL. Use the Network panel in developer tools to check 404 responses and invalid image formats.
2. Inspect the selected li element’s computed list-style-image and display. Check for a list-style shorthand or higher-priority rule that overrides the value. Also check whether display has changed to something such as flex, so the element no longer generates a list-item marker.
3. With outside positioning, insufficient indentation or a parent’s overflow setting can clip the marker. Check list padding and clipping. If a site policy blocks data URLs, replace the example image with an allowed image URL.

Nested lists can inherit this property too. To remove images from a nested list, explicitly apply list-style-image: none to that list and set its list-style-type to the desired value.

Preserve list meaning and accessibility

The blue circle here is decorative. Put important meaning such as completion, warnings or ratings in the actual list-item text, rather than only in a CSS image. CSS markers do not provide an HTML img-style alt attribute, so do not omit information on the assumption that the image will load or be announced.

Giving an ol the same image marker replaces its visible numbers with images. Keep the native numbers when readers need step numbering. Preserve the ul, ol and li structure, and check that the items and their sequence remain understandable without images. W3C definition of image list markers