Unfold Admin Module

Django-CFG’s Unfold Admin Module wraps the django-unfold  package with a type-safe UnfoldConfig Pydantic model, a dynamic navigation manager, OKLCH-based color theming synchronized with the Next.js UI package, and a system monitoring widget.

Features

• Type-safe configuration — UnfoldConfig Pydantic v2 model with full field validation
• Dynamic navigation — NavigationSection and NavigationItem with auto URL resolution and permission callbacks
• OKLCH color theming — semantic color palette (primary, success, warning, danger, info) synchronized with the frontend UI package
• Auto-injected CSS — CSS variables are base64-encoded and injected at startup without static file serving
• Login autofill — dev/demo credential prefill with smart environment detection
• System monitor — CPU, memory, and process metrics accessible from admin views
• Site dropdown — configurable header dropdown menu via SiteDropdownItem

Quick Start

# config.py
from django_cfg import DjangoConfig
from django_cfg.modules.django_unfold.models import UnfoldConfig
 
class MyConfig(DjangoConfig):
    unfold = UnfoldConfig(
        site_title="My Project Admin",
        site_header="My Project Administration",
        site_symbol="settings",
    )

Django-CFG adds unfold to INSTALLED_APPS before django.contrib.admin automatically when UnfoldConfig is set.

UnfoldConfig Fields

Site Branding

UI Settings

Dashboard

Navigation Sidebar

Login Autofill

Site Dropdown

Navigation

Use NavigationSection and NavigationItem to build a structured sidebar:

from django_cfg.modules.django_unfold.models import (
    UnfoldConfig,
    NavigationSection,
    NavigationItem,
)
 
class MyConfig(DjangoConfig):
    unfold = UnfoldConfig(
        site_title="My Admin",
        navigation=[
            NavigationSection(
                title="Content",
                separator=True,
                collapsible=True,
                items=[
                    NavigationItem(
                        title="Posts",
                        icon="article",
                        link="admin:blog_post_changelist",
                    ),
                    NavigationItem(
                        title="Categories",
                        icon="category",
                        link="admin:blog_category_changelist",
                    ),
                ],
            ),
            NavigationSection(
                title="Users",
                items=[
                    NavigationItem(
                        title="All Users",
                        icon="people",
                        link="admin:auth_user_changelist",
                    ),
                ],
            ),
        ],
    )

NavigationSection Fields

NavigationItem Fields

Automatic URL resolution: if link is a Django URL name (not starting with / or http), it is resolved via reverse_lazy. If the name follows the pattern admin:{app}_{model}_changelist, a permission callback is auto-generated that checks {app}.view_{model}.

Color Theming

Colors are specified in OKLCH format to be compatible with Unfold’s color-mix() CSS. The full semantic palette is defined in UnfoldConfig.get_color_scheme() and includes 10-step scales for:

• primary — blue (#3b82f6 / oklch(62.3% .214 259.815))
• success — green (#22c55e)
• warning — amber (#f59e0b)
• danger — red (#ef4444)
• info — sky blue (#0ea5e9)
• base — neutral grays
• font — semantic text colors for light and dark mode

These colors are synchronized with the @djangocfg/ui-core package CSS variables.

Login Autofill

Autofill is active when any of these conditions are true:

• DEBUG=True
• config.is_development is True
• dev_autofill_force=True

unfold = UnfoldConfig(
    site_title="Demo Admin",
    dev_autofill_email="[email protected]",
    dev_autofill_password="demo123",
    dev_autofill_force=True,  # works in production for demo sites
)

System Monitor

from django_cfg.modules.django_unfold import get_system_monitor
 
monitor = get_system_monitor()
metrics = monitor.get_system_metrics()
# Returns CPU %, memory %, disk %, load average, uptime, process count

See Also

• Changelog — recent updates to the Unfold module