Django admin theme build in Tailwind CSS by using django-unfold

Django, in general, is a mature and stable framework full of batteries that makes the development and most importantly maintenance of applications easy as a breeze. One of the batteries included by default in Django is django.contrib.admin. It is hard to imagine a Django project without using it at least to scaffold existing models and play with data during development.

Reasons for new admin theme

1. Granular customizations

As we are using Django admin on daily basis, we use to look for special modifications such as advanced sidebar configurations or datetime filters. Both features are not available in the default admin. More or less it is always possible to add custom features by overriding templates, but such customizations have to be specifically maintained per project.

2. Unification with other tooling

We like to have our tools shared between all projects as much as possible. In the case of Unfold, we wanted to have it written by using in Tailwind as Tailwind is our goto front end CSS framework for all the projects (especially written in React). Tailwind is one of the easiest CSS framework to start with and it makes easy for example for backend developers to make required changes on the front end.

3. Improved user experience

We like to have our tools shared between all projects as much as possible. In the case of Unfold, we wanted to have it written by using Tailwind as Tailwind is our go-to front-end CSS framework for all the projects (especially written in React). Tailwind is one of the easiest CSS frameworks to start with and it makes it easy for example for backend developers to make required changes on the front end.

Integration with an existing project

In general, integrating Unfold into an existing admin panel is not hard at all. The crucial part, after the installation from PyPi of course, consists of two steps. Adding unfold into INSTALLED_APPS in settings.py and then when registering a new Django admin model, it is needed to inherit from unfold.models.ModelAdmin instead of django.contrib.admin.ModelAdmin.

# An obvious step of installation from PyPi repository
pip install django-unfold

# settings.py

INSTALLED_APPS = [
    "unfold",  # Unfold must be before django.contrib.admin
    "unfold.contrib.filter",  # Just in case you need custom filters
    "django.contrib.admin",
]

The main difference between Unfold and other admin themes is that it is needed to inherit from unfold.admin.ModelAdmin. The main reason for this decision was that we need to inject custom behavior into each registered model for example support for custom actions in the list display.

# admin.py
from django.contrib import admin
from unfold.admin import ModelAdmin

from .models import ModelA, ModelB

@admin.register(ModelA)
class AdminModelA(ModelAdmin):
    pass

@admin.register(ModelB)
class AdminModelB(ModelAdmin)
    pass

When you are writing your custom project, it is not a problem to change the class name from which the admin model is inheriting but it can be a problem in third-party apps which are not owned by you. In most cases, these apps have admin.py where they are registering custom admin models by using django.contrib.admin.ModelAdmin. These models without using a custom unfold.admin.ModelAdmin looks broken in Unfold and must be deregistered and registered again with proper inheritance.

# admin.py

from django.contrib import admin
from unfold.admin import ModelAdmin
from thirdpartyapp.models import ModelA


admin.deregister(ModelA)

@admin.register(ModelA)
class AdminModelA(ModelAdmin):
    pass

After this sligh change, everything will be looking allright in admin and it will be possible to use all features of Unfold in this newly registered third-party admin model.

Basic configuration

By default, there is no need to change any settings to get Unfold working in your project and it should work out of the box. In case of some customizations, all settings for Unfold are available in settings.py under UNFOLD dictionary.

Below you can see the basic settings for Unfold theme which can be changed within settings.py. If you have experience with changing the title of the admin area in a default admin, you know that for changing such a basic thing as the title of admin, it was necessary to create a new AdminSite which will override the default configuration. The full list of allowed options for the Unfold are available GitHub repository.

# settings.py

UNFOLD = {
    "SITE_TITLE": "My New Project",
    "SITE_HEADER": "Custom New Project Header", 
}