django-unfold Documentation

Unfold enhances the standard django.contrib.admin with a modern Tailwind CSS-based interface. Key features include:

• Navigation & UI: Sidebar navigation with icons, dark mode support, command palette for quick searching, and custom dashboard tools.
• Form Enhancements: Inline tabs, fieldset tabs, conditional fields (show/hide based on other values), and sortable inlines via drag-and-drop.
• Advanced Filtering & Widgets: Custom dropdowns, autocomplete, numeric, datetime, and text field filters; support for ArrayField and Trix WYSIWYG editor.
• Performance & UX: Infinite pagination for large datasets, paginated inlines, and compressed changeform modes.
• Customization: Theming options for colors, backgrounds, and border radius; support for custom favicons and environment labels.

You can globally apply ArrayWidget to all ArrayField instances in a ModelAdmin using the formfield_overrides attribute. By default, the widget renders as standard text inputs. If choices are provided to the widget, it automatically switches to a dropdown list interface.

from django.contrib import admin
from django.contrib.postgres.fields import ArrayField
from unfold.admin import ModelAdmin
from unfold.contrib.forms.widgets import ArrayWidget

@admin.register(MyModel)
class CustomAdminClass(ModelAdmin):
    formfield_overrides = {
        ArrayField: {
            "widget": ArrayWidget,
        }
    }

To optimize performance when handling tables with millions of records, use the InfinitePaginator. This paginator avoids expensive database COUNT operations by removing the upper limit on page numbers and simplifying navigation to only "Previous" and "Next" links.

When implementing InfinitePaginator, you must also set show_full_result_count = False in your ModelAdmin to prevent Django from attempting to calculate the total record count, which would negate the performance benefits.

from unfold.admin import ModelAdmin
from unfold.paginator import InfinitePaginator


class YourAdmin(ModelAdmin):
    paginator = InfinitePaginator
    show_full_result_count = False

Unfold actions are derived from standard Django actions but enhanced with Unfold's @action decorator. You can define actions within a ModelAdmin class and register them in the actions_list attribute. The @action decorator allows you to add a description and an icon.

from django.contrib import admin
from django.db.models import QuerySet
from django.http import HttpRequest
from unfold.admin import ModelAdmin
from unfold.decorators import action

@admin.register(User)
class UserAdmin(ModelAdmin):
    actions_list = ["custom_action"]

    @action(description="Custom action", icon="person")
    def custom_action(self, request: HttpRequest, queryset: QuerySet):
        pass

Map your custom admin site instance to a URL pattern in your project's urls.py using the .urls attribute of the site instance.

from django.urls import path
from .sites import custom_admin_site

urlpatterns = [
    path("admin/", custom_admin_site.urls),
]

You can inject custom CSS and JavaScript files across all pages of the Django Unfold admin interface by configuring the STYLES and SCRIPTS keys within the UNFOLD dictionary in your settings.py.

Both keys accept a list containing either strings or lambda functions. It is recommended to use lambda functions with Django's static() template tag to ensure correct path resolution.

Deployment Note: Always run python manage.py collectstatic during your production deployment process to ensure your custom static files are correctly gathered and served.

# settings.py

from django.templatetags.static import static

UNFOLD = {
    "STYLES": [
        lambda request: static("css/styles.css"),
    ],
    "SCRIPTS": [
        lambda request: static("js/scripts.js"),
    ],
}

To enable multi-language support in the Django Unfold admin interface, you must configure your Django settings to handle internationalization and locale middleware.

1. Add django.middleware.locale.LocaleMiddleware to your MIDDLEWARE setting.
2. Set USE_I18N = True.
3. Define your default LANGUAGE_CODE.
4. Define the available languages in the LANGUAGES setting.

# settings.py

MIDDLEWARE = [
    "django.middleware.locale.LocaleMiddleware",
]

LANGUAGE_CODE = "en"

USE_I18N = True

LANGUAGES = (
    ("de", _("German")),
    ("en", _("English")),
)

Unfold allows you to add expandable rows to Django admin changelists using the list_sections attribute on your ModelAdmin. When configured, rows will display an arrow button that reveals additional content.

Sections are implemented by defining classes that inherit from either TableSection or TemplateSection from unfold.sections and adding them to the list_sections list in your ModelAdmin.