django-iconx 0.1.0

CSS-only icon system for Django

django-iconx

CSS-only icon system for Django.

Generates a single CSS file from SVG icon sources (Lucide, Heroicons, or your own). No JavaScript, no icon fonts.

<i class="icon icon-search"></i>
<span class="icon icon-check text-2xl text-green-500"></span>
<!-- aria-hidden="true" hides decorative icons from screen readers -->
<i class="icon icon-search" aria-hidden="true"></i>

How it works and what the upsides are

Mono icons use mask-image with background-color: currentColor, so the SVG acts as a mask and the icon inherits text color. Multi-color icons use background-image to preserve original SVG colors.

The output is plain CSS classes: no runtime, no bundler plugin, no framework coupling. The approach is not Django-specific; Django is just a good fit because its static file conventions make wiring it up easy. Any stack that serves CSS and renders HTML can use the generated stylesheet directly.

.icon { display: inline-block; width: 1em; height: 1em; }

.icon-search, .icon-check { background-color: currentColor; mask-size: contain; mask-mode: alpha; }
.icon-search { mask-image: url("/static/icons/search.svg"); }

.icon-logo { background-image: url("/static/logos/logo.svg"); }

• currentColor + mask-image: icons inherit text color
• 1em sizing: icons scale with font size / Tailwind text-*
• Direct element styling, no ::before pseudo-element
• Tree-shakeable: PurgeCSS strips unused .icon-* rules

Browser support

CSS mask-image is supported unprefixed in all modern browsers since Dec 2023 (~97% global coverage). Tailwind v4 handles vendor prefixing automatically:

@import "tailwindcss";
@import "./static/iconx/icons.css";

Installation

uv add django-iconx

Full documentation at oliverhaas.github.io/django-iconx

License

MIT