unfold-admin

Django Unfold Admin

Modern Django admin theme with Tailwind CSS, HTMX, and Alpine.js. Replaces Django's default admin with a polished, feature-rich interface.

Quick Start

Installation

# settings.py - unfold MUST be before django.contrib.admin
INSTALLED_APPS = [
    "unfold",
    "unfold.contrib.filters",          # advanced filters
    "unfold.contrib.forms",            # array/wysiwyg widgets
    "unfold.contrib.inlines",          # nonrelated inlines
    "unfold.contrib.import_export",    # styled import/export
    "unfold.contrib.guardian",         # django-guardian integration
    "unfold.contrib.simple_history",   # django-simple-history integration
    "unfold.contrib.constance",        # django-constance integration
    "unfold.contrib.location_field",   # django-location-field integration
    # ...
    "django.contrib.admin",
]

Minimal Admin

from unfold.admin import ModelAdmin

@admin.register(MyModel)
class MyModelAdmin(ModelAdmin):
    pass  # inherits Unfold styling

Site Configuration

Replace the default AdminSite or configure via UNFOLD dict in settings. See references/configuration.md for the complete settings reference.

UNFOLD = {
    "SITE_TITLE": "My Admin",
    "SITE_HEADER": "My Admin",
    "SITE_SYMBOL": "dashboard",  # Material Symbols icon name
    "SIDEBAR": {
        "show_search": True,
        "navigation": [
            {
                "title": _("Navigation"),
                "items": [
                    {
                        "title": _("Dashboard"),
                        "icon": "dashboard",
                        "link": reverse_lazy("admin:index"),
                    },
                ],
            },
        ],
    },
}

Core Workflow

When building Unfold admin interfaces, follow this sequence:

1. Configure site - UNFOLD settings dict (branding, sidebar, theme)
2. Register models - Extend unfold.admin.ModelAdmin
3. Enhance display - @display decorator for list columns
4. Add actions - @action decorator for row/list/detail/submit actions
5. Configure filters - Replace default filters with Unfold filter classes
6. Override widgets - Apply Unfold widgets via formfield_overrides
7. Set up inlines - Use Unfold's inline classes with tabs, pagination, sorting
8. Build dashboard - @register_component + BaseComponent for KPI cards