Django RemixIcon

A simple Django package for integrating RemixIcon with Django admin and templates. Provides seamless icon selection with autocomplete, preview functionality, and template tags for easy icon rendering.

✨ Features

• 🎯 Simple Integration: Minimal configuration required
• 🔍 Autocomplete Widget: Fast icon search in Django admin
• 👁️ Live Preview: See icons as you type
• 📋 Template Tags: Easy icon rendering in templates
• 📱 Responsive: Works on mobile and desktop
• ⚡ Performance: Efficient search and caching
• 🎨 Customizable: Style to match your design
• 🔧 Inline Support: Works with Django admin inlines
• 🌙 Dark Mode: Supports dark themes

🚀 Quick Start

Installation

pip install django-remix-icon

Django Setup

Add to your INSTALLED_APPS:

INSTALLED_APPS = [
    # ... your other apps
    'django_remix_icon',
]

Include URLs in your project:

# urls.py
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('remix-icon/', include('django_remix_icon.urls')),
    # ... your other URLs
]

Basic Usage

In your models:

from django.db import models
from django_remix_icon.fields import IconField

class MenuItem(models.Model):
    name = models.CharField(max_length=100)
    icon = IconField()  # Simple icon field
    url = models.URLField()

class Category(models.Model):
    title = models.CharField(max_length=100)
    icon = IconField(blank=True, null=True)  # Optional icon

In your templates:

{% load remix_icon_tags %}

<!DOCTYPE html>
<html>
<head>
    <title>My Site</title>
    {% remix_icon_css %}  <!-- Include RemixIcon CSS -->
</head>
<body>
    <!-- Simple icon rendering -->
    <h1>{% remix_icon 'ri-home-line' %} Welcome</h1>

    <!-- Using model fields -->
    {% for item in menu_items %}
        <a href="{{ item.url }}">
            {% remix_icon item.icon %}
            {{ item.name }}
        </a>
    {% endfor %}

    <!-- With custom styling -->
    {% remix_icon 'ri-heart-fill' class='text-red-500' size='24' %}
</body>
</html>

Admin Integration:

# admin.py - No additional configuration needed!
from django.contrib import admin
from .models import MenuItem

@admin.register(MenuItem)
class MenuItemAdmin(admin.ModelAdmin):
    list_display = ('name', 'icon', 'url')
    # IconField automatically provides autocomplete widget

📖 Documentation

Complete documentation is available at django-remix-icon.readthedocs.io

• Installation Guide
• Quick Start Tutorial
• Template Tags Reference
• Customization Guide
• API Documentation

🎭 Template Tags

Django RemixIcon provides several template tags for flexible icon rendering:

{% load remix_icon_tags %}

<!-- Basic icon -->
{% remix_icon 'ri-star-line' %}

<!-- Icon with attributes -->
{% remix_icon 'ri-heart-fill' class='love-icon' size='20' %}

<!-- Icon with text -->
{% remix_icon_with_text 'ri-download-line' 'Download' class='btn' %}

<!-- Conditional rendering -->
{% if item.icon|is_remix_icon %}
    {% remix_icon item.icon %}
{% endif %}

<!-- Get icon lists -->
{% remix_icon_list category='user' limit=10 as user_icons %}
{% for icon in user_icons %}
    {% remix_icon icon %}
{% endfor %}

🎨 Admin Widget Features

The Django admin integration provides:

Autocomplete Search

• Fast Search: Find icons quickly by typing
• Smart Filtering: Matches icon names and categories
• Keyboard Navigation: Use arrow keys and Enter

Live Preview

• Visual Feedback: See icons as you select them
• Icon Information: Shows icon name and category
• Responsive Design: Works on all screen sizes

Django Integration

• No Configuration: Works out of the box
• Inline Support: Works with TabularInline and StackedInline
• Validation: Ensures only valid icons are selected

🔧 Customization

Custom Widget Styling

/* Custom styles for your theme */
.remix-icon-widget {
    max-width: 500px;
}

.icon-search-input {
    border-radius: 8px;
    padding: 12px 16px;
}

.icon-preview {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    border-radius: 8px;
}

Custom Form Field

from django import forms
from django_remix_icon.fields import IconFormField

class CustomForm(forms.Form):
    icon = IconFormField(required=False)

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.fields['icon'].widget.attrs.update({
            'class': 'my-custom-icon-widget'
        })

📱 Examples

Navigation Menu

# models.py
class NavigationItem(models.Model):
    title = models.CharField(max_length=100)
    icon = IconField()
    url = models.URLField()
    order = models.PositiveIntegerField(default=0)

    class Meta:
        ordering = ['order']

<!-- template.html -->
{% load remix_icon_tags %}

<nav class="main-nav">
    {% for item in navigation_items %}
        <a href="{{ item.url }}" class="nav-item">
            {% remix_icon item.icon class='nav-icon' %}
            <span>{{ item.title }}</span>
        </a>
    {% endfor %}
</nav>

Dashboard Cards

# models.py
class DashboardCard(models.Model):
    title = models.CharField(max_length=100)
    icon = IconField()
    description = models.TextField()
    value = models.CharField(max_length=50)
    color = models.CharField(max_length=20, default='blue')

<!-- dashboard.html -->
{% for card in dashboard_cards %}
    <div class="dashboard-card card-{{ card.color }}">
        <div class="card-icon">
            {% remix_icon card.icon size='32' %}
        </div>
        <div class="card-content">
            <h3>{{ card.title }}</h3>
            <p class="card-value">{{ card.value }}</p>
            <p class="card-description">{{ card.description }}</p>
        </div>
    </div>
{% endfor %}

Status Indicators

{% for task in tasks %}
    <div class="task-item">
        {% if task.completed %}
            {% remix_icon 'ri-check-circle-fill' class='text-green-500' %}
        {% elif task.in_progress %}
            {% remix_icon 'ri-time-line' class='text-blue-500' %}
        {% else %}
            {% remix_icon 'ri-circle-line' class='text-gray-400' %}
        {% endif %}
        <span>{{ task.name }}</span>
    </div>
{% endfor %}

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/brktrlw/django-remix-icon.git
cd django-remix-icon

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -e .[dev]

Quick Contribution Guide

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run code formatting (black, isort, flake8)
5. Commit your changes (git commit -am 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📋 Requirements

• Python: 3.8+
• Django: 3.2+
• Browser: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+

🔄 Compatibility

Django Version	Python Version	Status
5.0	3.10, 3.11, 3.12	✅ Supported
4.2 (LTS)	3.8, 3.9, 3.10, 3.11, 3.12	✅ Supported
4.1	3.8, 3.9, 3.10, 3.11	✅ Supported
4.0	3.8, 3.9, 3.10, 3.11	✅ Supported
3.2 (LTS)	3.8, 3.9, 3.10, 3.11	✅ Supported

🏗️ Architecture

django-remix-icon/
├── django_remix_icon/
│   ├── fields.py          # IconField model field
│   ├── widgets.py         # Admin widgets
│   ├── views.py           # AJAX search views
│   ├── templatetags/      # Template tags
│   ├── static/            # CSS and JavaScript
│   └── templates/         # Widget templates
├── docs/                  # Documentation

🎯 Philosophy

Django RemixIcon follows these principles:

• Simplicity: Minimal configuration, maximum functionality
• Performance: Efficient search and rendering
• Flexibility: Customizable but with sensible defaults
• Integration: Seamless Django admin experience
• Accessibility: Keyboard navigation and screen reader support

🔍 FAQ

Q: How many icons are available? A: Over 2,000 icons from RemixIcon v4.7.0, covering all major categories.

Q: Does it work with Django admin inlines? A: Yes! The widget works perfectly with both TabularInline and StackedInline.

Q: Can I customize the widget appearance? A: Absolutely! The widget includes CSS classes for easy customization.

Q: Is there a performance impact? A: Minimal. The widget uses debounced search and efficient caching.

Q: Does it work on mobile? A: Yes, the widget is fully responsive and touch-friendly.

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgments

• RemixIcon for the amazing icon library
• Django for the excellent web framework
• All contributors who help improve this package

📈 Changelog

See CHANGELOG.md for a list of changes and migration guides.

🔗 Links

• Documentation: https://django-remix-icon.readthedocs.io/
• PyPI: https://pypi.org/project/django-remix-icon/
• GitHub: https://github.com/brktrlw/django-remix-icon
• Issues: https://github.com/brktrlw/django-remix-icon/issues
• RemixIcon: https://remixicon.com/

---