Django Unfold

SKILL.md

---
name: django-unfold
description: >
  Expert guidance for building advanced Django admin interfaces with django-unfold (v0.56+).
  Use this skill whenever the user mentions django-unfold, unfold admin, UnfoldModelAdmin,
  or wants to build, customize, or debug a Django admin panel with Unfold. Covers setup,
  ModelAdmin options, theming/colors, sidebar navigation, tabs (fieldset/inline/changelist/
  dynamic), inlines (sortable/paginated/nested/nonrelated), dashboard & components, actions
  (all 5 types + dropdown), filters (all types), conditional fields, sections/expandable rows,
  datasets, custom pages, crispy forms, Tailwind custom styles, @display and @action decorators,
  and all 10 third-party integrations. Always trigger this skill when the user asks to build any
  Django admin feature and django-unfold is present in the project, even if Unfold is not
  explicitly mentioned.
---

# Django Unfold Skill

Django Unfold is a modern admin theme for Django built on Tailwind CSS. It is a **drop-in
enhancement** of `django.contrib.admin` — fully compatible with all native Django admin
patterns while adding UI, components, and developer-friendly features.

**Current stable version: 0.90.x** (Django 5.0+ required from v0.90; dropped Django 4.2)

---

## ⚠️ Critical Rules — Always Apply

**Rule 1: Every ModelAdmin must inherit from `unfold.admin.ModelAdmin`**

```python
# ✅ CORRECT
from unfold.admin import ModelAdmin

@admin.register(MyModel)
class MyModelAdmin(ModelAdmin):
    pass

# ❌ WRONG — loses all styling and Unfold features
from django.contrib.admin import ModelAdmin  # never use this base
```

**Rule 2: `INSTALLED_APPS` order — `"unfold"` must precede `"django.contrib.admin"`**

```python
INSTALLED_APPS = [
    "unfold",                           # REQUIRED FIRST
    "unfold.contrib.filters",           # optional: advanced filters
    "unfold.contrib.forms",             # optional: ArrayWidget, WysiwygWidget, crispy
    "unfold.contrib.inlines",           # optional: NonrelatedInline
    "unfold.contrib.import_export",     # optional: django-import-export
    "unfold.contrib.simple_history",    # optional: django-simple-history
    "unfold.contrib.guardian",          # optional: django-guardian
    "unfold.contrib.constance",         # optional: django-constance
    "unfold.contrib.location_field",    # optional: django-location-field
    "django.contrib.admin",             # AFTER unfold
]
```

**Rule 3: Inlines also need Unfold base classes**

```python
from unfold.admin import StackedInline, TabularInline  # not django.contrib.admin
```

**Rule 4: User & Group models need manual re-registration** — see `references/installation.md`

---

## Core ModelAdmin Options Reference

```python
from unfold.admin import ModelAdmin
from unfold.contrib.forms.widgets import ArrayWidget, WysiwygWidget
from django.db import models

@admin.register(MyModel)
class MyModelAdmin(ModelAdmin):
    # ── Changelist layout ────────────────────────────────────────────
    list_fullwidth = False               # expand to full page width
    list_filter_sheet = True             # filters as bottom sheet (False = sidebar)
    list_filter_submit = False           # show Apply button in filter panel
    list_horizontal_scrollbar_top = False
    list_disable_select_all = False

    # ── Change form UX ────────────────────────────────────────────────
    compressed_fields = True             # compact field display
    warn_unsaved_form = True             # warn before leaving unsaved
    show_add_link = True                 # show Add button
    change_form_show_cancel_button = False

    # Custom template injection (HTML snippets, not full templates)
    change_form_before_template = "myapp/before_form.html"    # inside form, top
    change_form_after_template = "myapp/after_form.html"      # inside form, bottom
    change_form_outer_before_template = "myapp/outer_top.html"
    change_form_outer_after_template = "myapp/outer_bottom.html"

    # ── Readonly field post-processing ───────────────────────────────
    readonly_preprocess_fields = {
        "html_field": "html.unescape",
        "text_field": lambda content: content.strip(),
    }

    # ── Widget overrides ─────────────────────────────────────────────
    formfield_overrides = {
        models.TextField: {"widget": WysiwygWidget},
        # ArrayField: {"widget": ArrayWidget},  # for PostgreSQL ArrayField
    }

    # ── Actions (5 types) — see references/actions.md ────────────────
    actions_list = []        # above changelist (global)
    actions_row = []         # per-row in changelist table
    actions_detail = []      # top of change form header
    actions_submit_line = [] # near Save button in change form

    # ── Conditional fields — see references/forms-fields.md ──────────
    conditional_fields = {
        "field_name": "other_field == 'value'",  # Alpine.js expression
    }

    # ── Expandable row sections — see references/forms-fields.md ─────
    list_sections = []   # [SectionClass, ...]

    # ── Datasets on change form — see references/forms-fields.md ─────
    change_form_datasets = []  # [DatasetClass, ...]
```

---

## @display Decorator

**Always use `unfold.decorators.display`**, not Django's built-in.

```python
from unfold.decorators import display

class OrderAdmin(ModelAdmin):
    list_display = ["show_customer", "show_status", "show_priority"]

    # Two-line cell: main heading + subtitle
    @display(header=True)
    def show_customer(self, obj):
        return obj.full_name, obj.email   # tuple: (main, subtitle)

    # Colored status badge mapped from field values
    @display(
        description="Status",
        ordering="status",
        label={
            "PENDING":   "warning",   # orange
            "ACTIVE":    "info",      # blue
            "COMPLETED": "success",   # green
            "FAILED":    "danger",    # red
        },
    )
    def show_status(self, obj):
        return obj.status

    # Boolean label with default color
    @display(description="VIP", label=True)
    def show_priority(self, obj):
        return obj.is_vip
```

→ Full `@display` and `@action` decorator docs: **`references/decorators.md`**

---

## Reference Files — When To Read Each

Read the relevant file before implementing any feature in that area.
Each reference file contains explicit pointers to related files.

| Reference File | Read When You Need To... |
|---|---|
| `references/installation.md` | Set up from scratch, configure User/Group, run parallel admin |
| `references/configuration.md` | Understand any `UNFOLD = {...}` key: title, login, callbacks, favicons, env |
| `references/theming.md` | Change colors (OKLCH), sidebar nav, icons/badges, Tailwind custom CSS |
| `references/actions.md` | Add list/row/detail/submitline/dropdown actions, permissions, form actions |
| `references/filters.md` | Add text/date/dropdown/numeric/autocomplete/checkbox/radio/horizontal filters |
| `references/tabs.md` | Add fieldset tabs, inline tabs, changelist tabs, changeform tabs, dynamic tabs |
| `references/inlines.md` | Configure inlines: options, sortable, paginated, nested, nonrelated |
| `references/dashboard-components.md` | Build dashboards, use components (card/chart/table/progress/tracker/cohort) |
| `references/forms-fields.md` | Conditional fields, sections (expandable rows), datasets, crispy forms, JsonField |
| `references/decorators.md` | Full @display options (header, label, mapping) and @action decorator options |
| `references/integrations.md` | All 10 third-party packages: celery-beat, import-export, guardian, constance, etc. |
| `references/advanced.md` | Custom pages, custom sites, sortable changelist, command palette, multi-language |

---

## Common Pitfalls

- **Styles missing in production** → run `collectstatic`
- **Tailwind conflict on Unfold ≥ 0.56** → don't load a Tailwind 3 CSS file; use `UNFOLD["COLORS"]` or Tailwind 4
- **Custom pages not in sidebar** → add manually to `UNFOLD["SIDEBAR"]["navigation"]`
- **Third-party admin unstyled** (celery-beat, etc.) → unregister and re-register with `unfold.admin.ModelAdmin`
- **`list_filter` on Datasets** → not supported; filter via `get_queryset()` instead
- **Django 4.2** → not supported from Unfold v0.90+