Metadata-Version: 2.4
Name: django-iconx
Version: 0.2.0
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 :: 3 - 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. No JavaScript, no icon fonts.

```console
python manage.py iconx add lucide
```

```html
<i class="icon icon-search"></i>
<span class="icon icon-check text-2xl text-green-500"></span>
```

Built-in support for Lucide, Heroicons, Tabler, Phosphor, Bootstrap Icons, and Remix. Or bring your own SVGs.

## 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.

```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";
```

## Quick start

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

```python
INSTALLED_APPS = ["django_iconx", ...]
STATICFILES_DIRS = [BASE_DIR / "static"]
```

```console
python manage.py iconx add lucide
```

That downloads Lucide icons and generates the CSS. Include the CSS in your template or Tailwind entry point and use icons via class names. See the full documentation at [oliverhaas.github.io/django-iconx](https://oliverhaas.github.io/django-iconx/) for custom SVGs, multiple icon sets, and configuration options.

## License

MIT
