CSS list-style-image Property
Use the list-style-image CSS property to set an image instead of the list item marker. Definition of the property, values and examples.
The CSS list-style-image property replaces the default list item marker (the disc, circle, or number) with an image of your choice. It is the simplest way to give an <ol> or <ul> custom bullets — a checkmark, an arrow, an icon — without adding extra markup.
This page covers what the property does, the values it accepts, how the marker is sized, common gotchas, and how it fits into the list-style shorthand.
When to use it
Reach for list-style-image when you want decorative bullets that come from a single, small image and you do not need to control the bullet's exact size or spacing. If you need precise control over the marker (size, gap, alignment), the modern approach is a ::marker pseudo-element or a background-image on each <li> with padding-left — list-style-image gives you no way to resize the image, so an oversized graphic will dominate the line.
How the marker is sized
If the image has an intrinsic width and height, they are used directly as the marker size. If the image has an intrinsic aspect ratio plus only one intrinsic dimension, the missing dimension is calculated from the ratio. Because there is no CSS to scale the marker, prepare the image at the size you want it to appear (typically 16×16 or smaller).
The list-style-image property applies to list items and any element with display set to list-item. By default that means <li> elements, but you can also set it on the parent <ol> or <ul>, where it is inherited by the list items.
If the image fails to load, the marker falls back to the list-style-type value (a disc by default). Always keep a sensible list-style-type so broken images don't leave your list with no bullets at all.
| Initial Value | none |
|---|---|
| Applies to | List items. |
| Inherited | Yes. |
| Animatable | No. |
| Version | CSS1 |
| DOM Syntax | object.style.listStyleImage = 'url("image.jpg")'; |
Syntax
Syntax of CSS list-style-image Property
list-style-image: none | <url> | image-set() | initial | inherit;Example of the list-style-image property:
Example of CSS list-style-image Property with none value
<!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>Result
![CSS list-style-image Property](/uploads/media/default/0001/04/3253cd4b1e6f2bdbce6333da58573f6d8a9a0d53.png "CSS list-style-image none result" =420x)
Example of the list-style-image property with an attached source URL of the image:
Example of CSS list-style-image Property
<!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>Using the list-style shorthand
In practice the image is usually set together with the marker type and position through the list-style shorthand. The two rules below are equivalent:
/* 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");
}The square here is the fallback marker used while the image loads or if it is unavailable. See list-style-position for the difference between inside and outside.
Values
| Value | Description | Play it |
|---|---|---|
none | No image is shown. The marker defined by list-style-type is used instead. This is the default value. | Play it » |
<url> | The source URL of the image to use as the list item marker, written as url("path/to/image.png"). | Play it » |
image-set() | A set of image candidates the browser chooses from based on the rendering environment, e.g. screen resolution. Lets you serve a sharper image to high-DPI displays. | Play it » |
initial | Resets the property to its default value (none). | Play it » |
inherit | Inherits the value from the parent element. |
Browser support and accessibility
list-style-image is supported in every modern browser (it dates back to CSS1). Two things to keep in mind:
- The image is purely decorative — screen readers do not announce it, and there is no
alttext. Don't encode meaning in the bullet that isn't also present in the list text. - Marker color follows the text
colorforlist-style-type, but an image keeps its own colors. If you want the bullet to match the text color, use a::markerorbackground-imageapproach instead.