A simple Django package for integrating RemixIcon with Django admin and templates
Project description
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
TabularInlineandStackedInline - 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
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run code formatting (black, isort, flake8)
- Commit your changes (
git commit -am 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - 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/
โญ Star this repo if you find it useful!
Made with โค๏ธ for the Django community
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
django_remix_icon-2.0.2.tar.gz
(82.0 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file django_remix_icon-2.0.2.tar.gz.
File metadata
- Download URL: django_remix_icon-2.0.2.tar.gz
- Upload date:
- Size: 82.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8b5d7ede37e814e9861244e1da47d8d307001a78856aa0811e85f0a39812d1c2
|
|
| MD5 |
7721e38e6161037d1167d8570169ee90
|
|
| BLAKE2b-256 |
113bc6ae5f7db779ca04216c1a2330965a89c01b20480ba4a6e33d9d10c89371
|
File details
Details for the file django_remix_icon-2.0.2-py3-none-any.whl.
File metadata
- Download URL: django_remix_icon-2.0.2-py3-none-any.whl
- Upload date:
- Size: 44.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
dc76581ba8d4c39c1e300b5136e5be0be5e3c71009465eebb02b87ad5ff4cd5f
|
|
| MD5 |
254adf40a09e85b90d2d06c810af0046
|
|
| BLAKE2b-256 |
9066579af8b781788b174acf7ca86c484219bf8b65659cb5b37b416fa534a1c2
|
