Mastering Django-Unfold: Building a Custom E-Commerce Admin Dashboard

In this guide, we’ll explore how to create a powerful admin dashboard using Django-Unfold. You'll learn to set up custom models, configure advanced filters, implement actions, and display key performance indicators (KPIs) — all within an engaging Unfold-themed interface. This Q&A format answers the most common questions about building such a dashboard. Use the links below to jump to specific topics:

• What is Django-Unfold and why should I use it for admin dashboards?
• How do I install Django-Unfold and set up a new project?
• What are the key config steps for enabling Unfold's modern admin theme?
• How can I create custom e-commerce models for the shop app?
• How do I add custom filters, actions, and tabs to the admin interface?
• How can I display KPIs and a custom homepage in the Unfold dashboard?

What is Django-Unfold and why should I use it for admin dashboards?

Django-Unfold is a modern, themeable admin interface package for Django that replaces the default admin with a cleaner, more intuitive design. It provides built-in support for dark mode, custom sidebars, dashboard callbacks, and KPI widgets. Using Unfold lets you quickly build an admin dashboard that looks professional and is easy to navigate, especially for complex applications like e-commerce platforms. It integrates seamlessly with Django’s admin and offers advanced filtering, actions, and tabbed views out of the box.

How do I install Django-Unfold and set up a new project?

Start by installing Django, Django-Unfold, and Pillow (for image handling) using pip: pip install django django-unfold Pillow. Then create a new Django project and a shop app. Unfold requires minimal configuration: add unfold and its contrib apps to INSTALLED_APPS before django.contrib.admin. Also configure CSRF_TRUSTED_ORIGINS and SECURE_PROXY_SSL_HEADER if running behind a proxy (e.g., in Colab). Finally, run migrations and create a superuser to access the admin panel.

What are the key config steps for enabling Unfold's modern admin theme?

After installation, you need to define UNFOLD in your settings.py. This dictionary controls site title, sidebar navigation, dashboard callbacks, and more. For example, set SITE_TITLE, SITE_HEADER, and SITE_URL. Add custom navigation items under NAVIGATION to group your models. You can also enable tabs, filters, and actions per model by registering them in admin.py using Unfold mixins. The theme automatically applies a clean, responsive design.

How can I create custom e-commerce models for the shop app?

Define models like Category, Product, Customer, Order, and OrderItem in shop/models.py. Use fields like CharField, DecimalField, ForeignKey, and DateField to represent real-world data. For example, a Product might have a name, price, category (FK), and image. After defining models, run makemigrations and migrate. Seed the database with sample data using a management command or fixture to test the dashboard.

How do I add custom filters, actions, and tabs to the admin interface?

In your admin.py, register models with Unfold’s ModelAdmin subclasses. To add filters, use list_filter and Unfold’s custom filter classes (e.g., DropdownFilter). For actions, define methods decorated with @admin.action. Tabs are created using UnfoldAdminTabbedPage or by overriding get_tabs. You can also add badges to display counts or statuses next to model names in the sidebar. Unfold’s documentation provides detailed examples for each feature.

How can I display KPIs and a custom homepage in the Unfold dashboard?

Unfold supports dashboard callbacks that return KPI cards. Create a function (e.g., dashboard_callback) that computes metrics like total orders, revenue, or new customers. Register it in UNFOLD settings under DASHBOARD_CALLBACKS. For a custom homepage, override the admin index template or use Unfold’s AdminIndexView subclass. This gives you full control over the layout, allowing you to embed charts, tables, and KPI widgets.