xeolux-iconkit 1.1.0

A reusable Django icon library with 300+ SVG icons — outline, solid, minimal, brand + thematic packs.

Xeolux IconKit

A professional, reusable SVG icon library for Django — outline · solid · minimal · brand

---

Features

• Inline SVG — no fonts, no external requests, fully offline
• 4 icon styles — outline, solid, minimal, brand
• Django template tag — simple, expressive syntax
• Customisable — size, color, CSS class, and any HTML attribute
• Bootstrap & TailwindCSS compatible — uses currentColor throughout
• Accessible — aria-hidden by default, supports aria_label
• Zero JavaScript — pure server-side rendering

---

Installation

pip install xeolux-iconkit

Add to INSTALLED_APPS in your Django settings:

INSTALLED_APPS = [
    ...
    "xeolux_iconkit",
]

---

Quick Start

Load the template tag at the top of any template:

{% load iconkit %}

Then use the {% icon %} tag:

{# Basic usage #}
{% icon "home" %}

{# With size (number = px, or CSS units) #}
{% icon "user" size="24" %}
{% icon "settings" size="1.5rem" %}

{# With CSS class #}
{% icon "settings" class="text-primary" %}

{# Choose style #}
{% icon "phone" style="outline" %}
{% icon "phone" style="solid" %}
{% icon "phone" style="minimal" %}
{% icon "github" style="brand" %}

{# Custom color #}
{% icon "star" color="#f59e0b" %}

{# Full customisation #}
{% icon "bell" size="20" style="solid" class="icon-bell" aria_label="Notifications" %}

{# Dynamic name from context variable #}
{% icon icon_name size="24" %}

---

Template Tag Reference

{% icon NAME [size=VALUE] [style=STYLE] [color=HEX] [class=CSS] [ATTR=VALUE ...] %}

Argument	Type	Default	Description
NAME	string / variable	—	Icon name (e.g. "home")
size	string	—	Width & height — plain number ("24" → 24px) or CSS unit ("1.5rem")
style	string	outline	Icon variant: outline, solid, minimal, brand
color	string	—	CSS color property (works with currentColor fills)
class	string	—	Extra CSS classes on the <svg> element
aria_label	string	—	Renders as aria-label attribute (any _ becomes -)
any other	string	—	Passed as sanitised HTML attribute

---

Global Configuration

In your Django settings you can override the default style:

# settings.py
XEOLUX_ICONKIT_DEFAULT_STYLE = "solid"   # default: "outline"

---

Available Icons

Outline / Solid / Minimal

Name	Category
home	Navigation
user	User
settings	UI
phone	Contact
mail	Contact
search	UI
bell	UI
cart	E-commerce
menu	Navigation
close	UI
plus	UI
trash	UI
edit	UI
star	UI
warning	Status
check-circle	Status
chart	Dashboard
lock	Security

Brand

Name
github
twitter
linkedin
django

Adding your own icons: drop a .svg file in the appropriate style folder: xeolux_iconkit/static/xeolux_iconkit/icons/<style>/<name>.svg

---

Integration Examples

Bootstrap button with icon

{% load iconkit %}

<button class="btn btn-primary d-flex align-items-center gap-2">
  {% icon "plus" size="16" %} Ajouter
</button>

<button class="btn btn-danger d-flex align-items-center gap-2">
  {% icon "trash" size="16" %} Supprimer
</button>

TailwindCSS

{% load iconkit %}

<button class="flex items-center gap-2 px-4 py-2 bg-blue-600 text-white rounded-lg">
  {% icon "plus" size="16" class="text-white" %} Nouveau
</button>

Navbar

{% load iconkit %}

<nav>
  <a href="/">{% icon "home" size="20" %} Accueil</a>
  <a href="/profile/">{% icon "user" size="20" %} Profil</a>
  <a href="/settings/">{% icon "settings" size="20" %} Paramètres</a>
</nav>

Dashboard card

{% load iconkit %}

<div class="card p-4 flex gap-3">
  <div class="text-indigo-500">{% icon "chart" size="32" %}</div>
  <div>
    <h3>Statistiques</h3>
    <p>Vue globale de vos données</p>
  </div>
</div>

Django Admin (custom header)

# admin.py
from django.contrib import admin
from django.utils.safestring import mark_safe
from xeolux_iconkit.registry import get_icon_svg

class MyModelAdmin(admin.ModelAdmin):
    def get_list_display(self, request):
        return ["icon_col", "name"]

    def icon_col(self, obj):
        svg = get_icon_svg("star", style="solid")
        return mark_safe(f'<span style="color:#f59e0b">{svg}</span>')
    icon_col.short_description = "Icône"

---

Running the Demo

cd example
pip install -e ..
python manage.py runserver
# → http://127.0.0.1:8000/

---

Running Tests

pip install pytest pytest-django django
pytest tests/ -v

---

Project Structure

xeolux-iconkit/
├── xeolux_iconkit/                  # Django application
│   ├── __init__.py
│   ├── apps.py
│   ├── registry.py                  # Icon resolution logic
│   ├── templatetags/
│   │   ├── __init__.py
│   │   └── iconkit.py               # {% icon %} template tag
│   └── static/
│       └── xeolux_iconkit/
│           └── icons/
│               ├── outline/         # Stroke icons (1.5px)
│               ├── solid/           # Filled icons
│               ├── minimal/         # Ultra-thin icons (1px)
│               └── brand/           # Brand / logo icons
├── example/                         # Demo Django project
│   ├── demo_project/
│   └── demo/
│       └── templates/demo/index.html
├── tests/
│   └── test_iconkit.py
├── setup.py
├── setup.cfg
├── pyproject.toml
├── MANIFEST.in
├── LICENSE
└── README.md

---

Contributing

1. Fork the repository
2. Add your SVG icon to the correct style folder
3. Follow the naming convention: kebab-case.svg
4. Ensure the SVG uses currentColor for stroke/fill
5. Open a Pull Request

---

License

MIT © Xeolux