Tailwind CSS - List Style Image

Customizing List Markers with List Style Image

Tailwind CSS provides utilities to customize the markers of list items, allowing you to move beyond default bullets and numbers. While the list-style-image property offers a direct way to use an image as a marker, modern CSS techniques often provide more control and flexibility.

The list-image-none Utility

Tailwind includes a single core utility for list-style-image out of the box.

Class	CSS Properties
list-image-none	list-style-image: none;

Using Arbitrary Values for Custom Images

With Tailwind’s JIT (Just-In-Time) compiler, you can use arbitrary values to set a custom list image directly in your HTML. For self-contained examples, an SVG data URI is an excellent choice as it doesn’t require a separate image file.

Example: Custom SVG Marker with Arbitrary Value

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Tailwind CSS List Style Image Demo</title>
    <link href="/dist/output.css" rel="stylesheet">
</head>
<body class="bg-slate-50 p-8">

    <div class="max-w-md mx-auto bg-white p-6 rounded-lg shadow">
        <h2 class="text-xl font-bold text-slate-800 mb-4">Recipe Ingredients</h2>

        <!--
            We use an arbitrary value to set the list-style-image to a checkmark SVG.
            The SVG is URL-encoded to be safely used in a data URI.
            `pl-5` is used to provide space for the custom marker.
        -->
        <ul class="list-inside pl-5 list-image-[url('data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2020%2020%22%20fill%3D%22%2322c55e%22%3E%3Cpath%20fill-rule%3D%22evenodd%22%20d%3D%22M10%2018a8%208%200%20100-16%208%208%200%20000%2016zm3.707-9.293a1%201%200%2000-1.414-1.414L9%2010.586%207.707%209.293a1%201%200%2000-1.414%201.414l2%202a1%201%200%20001.414%200l4-4z%22%20clip-rule%3D%22evenodd%22%20%2F%3E%3C%2Fsvg%3E')]">
            <li class="mb-2 text-slate-700">1 cup strawberries</li>
            <li class="mb-2 text-slate-700">1/2 cup blueberries</li>
            <li class="mb-2 text-slate-700">1 banana, sliced</li>
            <li class="text-slate-700">1/4 cup almond milk</li>
        </ul>
    </div>

</body>
</html>

Best Practice: Extending Your Theme

Hardcoding data URIs in your HTML can be repetitive. A cleaner, more maintainable approach is to define your custom list images in tailwind.config.js. This allows you to create a reusable utility class.

// tailwind.config.js
const checkmarkSvg = `url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20' fill='%2322c55e'%3E%3Cpath fill-rule='evenodd' d='M10 18a8 8 0 100-16 8 8 0 000 16zm3.707-9.293a1 1 0 00-1.414-1.414L9 10.586 7.707 9.293a1 1 0 00-1.414 1.414l2 2a1 1 0 001.414 0l4-4z' clip-rule='evenodd' /%3E%3C/svg%3E")`;

module.exports = {
  theme: {
    extend: {
      listStyleImage: {
        checkmark: checkmarkSvg,
      }
    }
  }
}

// Now in your HTML, you can simply use:
// <ul class="list-inside pl-5 list-image-checkmark">...</ul>

Limitations and Modern Alternatives

The list-style-image property has significant limitations: you have very little control over the marker’s size, position, or alignment. For this reason, a more common and flexible modern approach is to hide the default list marker and use a ::before pseudo-element with a background image. This provides full control with CSS.

Advanced Technique: Using Pseudo-elements

While this requires a bit of custom CSS or a simple Tailwind plugin, the concept is important to understand for advanced styling.

/* in your custom CSS file */
.list-custom-marker li::before {
    content: '';
    display: inline-block;
    width: 1em;
    height: 1em;
    margin-right: 0.5em;
    background-image: url('path/to/your/icon.svg');
    background-size: contain;
    background-repeat: no-repeat;
}

/* In your HTML */
<ul class="list-none list-custom-marker">
    <li>List item with full control over its marker.</li>
</ul>