Metadata-Version: 2.4
Name: django-iconx
Version: 0.1.0a3
Summary: CSS-only icon system for Django
Project-URL: Homepage, https://github.com/oliverhaas/django-iconx
Project-URL: Documentation, https://oliverhaas.github.io/django-iconx/
Project-URL: Repository, https://github.com/oliverhaas/django-iconx.git
Project-URL: Changelog, https://oliverhaas.github.io/django-iconx/reference/changelog/
Author-email: Oliver Haas <ohaas@e1plus.de>
License: MIT
License-File: LICENSE
Keywords: css,django,icons
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: django<7,>=5.2
Description-Content-Type: text/markdown

# django-iconx

[![PyPI version](https://img.shields.io/pypi/v/django-iconx.svg?style=flat)](https://pypi.org/project/django-iconx/)
[![Python versions](https://img.shields.io/pypi/pyversions/django-iconx.svg)](https://pypi.org/project/django-iconx/)
[![CI](https://github.com/oliverhaas/django-iconx/actions/workflows/ci.yml/badge.svg)](https://github.com/oliverhaas/django-iconx/actions/workflows/ci.yml)

CSS-only icon system for Django.

![django-iconx demo](docs/assets/demo.png)

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

```html
<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` -- 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.

```css
.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:

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

## Installation

```console
uv add django-iconx
```

Full documentation at [oliverhaas.github.io/django-iconx](https://oliverhaas.github.io/django-iconx/)

## License

MIT
