Building Advanced Django-Unfold Dashboards: Custom Models, Filters, and KPIs

How to Build a Django-Unfold Admin Dashboard with Custom Models, Filters, Actions, and KPIs

Django-Unfold provides a modern UI layer for the native Django admin, allowing for complex dashboard callbacks and custom KPI cards. This framework enables developers to create high-density, professional back-offices with minimal boilerplate while maintaining the power of Django’s ModelAdmin.

Why This Matters

Native Django admin panels are often insufficient for data-driven e-commerce operations that require real-time metrics and sophisticated filtering. Transitioning to Unfold allows for the implementation of features like dashboard callbacks for revenue tracking and conditional fields for pricing, reducing the need for building entirely custom internal tools from scratch. This approach significantly lowers the engineering overhead required to maintain bespoke administrative interfaces while providing a superior user experience for non-technical staff.

Key Insights

• Dashboard Callbacks: The DASHBOARD_CALLBACK setting enables the injection of dynamic context such as 30-day revenue and order status summaries into the admin homepage.
• Advanced Filtering: Integration with unfold.contrib.filters provides specialized UI for RangeNumericFilter and ChoicesDropdownFilter to handle large datasets efficiently.
• Action Customization: ModelAdmin supports actions_list, actions_row, and actions_detail to provide granular control over record management directly from the list view.
• Visual Data Representation: The @display decorator with label attributes allows for color-coding statuses like ‘Draft’, ‘Active’, and ‘Archived’ for immediate visual recognition.
• Conditional UI: The conditional_fields attribute allows developers to toggle the visibility of form fields based on the state of other fields, such as showing discount percentages only when a discount toggle is active.

Working Examples

Configuration of the UNFOLD dictionary in Django settings.py to customize the sidebar and dashboard.

UNFOLD = { 'SITE_TITLE': 'Acme Shop Admin', 'SITE_HEADER': 'Acme Shop', 'DASHBOARD_CALLBACK': 'shop.utils.dashboard_callback', 'SIDEBAR': { 'show_search': True, 'navigation': [ { 'title': 'Catalog', 'items': [ { 'title': 'Products', 'icon': 'inventory_2', 'link': reverse_lazy('admin:shop_product_changelist'), 'badge': 'shop.utils.products_badge' } ] } ] } }

Implementation of ProductAdmin using Unfold’s ModelAdmin with conditional fields and visual status labels.

@admin.register(Product) class ProductAdmin(ModelAdmin): list_display = ('name', 'sku', 'show_status', 'stock_badge') conditional_fields = {'discount_percent': 'has_discount == true'} @display(description='Status', label={'draft': 'info', 'active': 'success', 'archived': 'warning'}) def show_status(self, obj): return obj.get_status_display(), obj.status

Practical Applications

• E-commerce Back-office: Utilizing custom OrderAdmin actions to bulk update shipping statuses or duplicate orders for fast re-entry. Pitfall: Over-customizing the admin can lead to performance degradation if complex aggregations are performed in list_display without database optimization.
• Inventory Control: Implementing stock_badge logic to provide immediate visual warnings for low-stock items. Pitfall: Neglecting autocomplete_fields for large foreign key relations like Categories can cause significant browser lag during data entry.
• Business Intelligence: Custom index templates showing top-performing categories and order status distributions directly on the landing page. Pitfall: Hardcoding KPI logic in templates instead of using context processors or callbacks makes the dashboard difficult to maintain as business requirements evolve.

References:

• https://www.marktechpost.com/2026/05/14/how-to-build-a-django-unfold-admin-dashboard-with-custom-models-filters-actions-and-kpis/