{"slug":"unfold-admin","title":"unfold-admin","summary":"Django Unfold admin theme - build, configure, and enhance modern Django admin interfaces with Unfold. Use when working with: (1) Django admin UI customisation or theming, (2) Unfold ModelAdmin, inlines, actions, filters, widgets, or decorators, (3) Admin dashboard components and ","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-30T19:37:29.334176Z","repo":{"url":"https://github.com/0xDarkMatter/claude-mods","stars":43,"forks":7,"license":"MIT","updatedAt":"2026-09-30T15:18:48Z"},"bodyHtml":"
\n

name: unfold-admin\ndescription: \"Django Unfold admin theme - build, configure, and enhance modern Django admin interfaces with Unfold. Use when working with: (1) Django admin UI customisation or theming, (2) Unfold ModelAdmin, inlines, actions, filters, widgets, or decorators, (3) Admin dashboard components and KPI cards, (4) Sidebar navigation, tabs, or conditional fields, (5) Any mention of 'unfold', 'django-unfold', or 'unfold admin'. Covers the full Unfold feature set: site configuration, actions system, display decorators, filter types, widget overrides, inline variants, dashboard components, datasets, sections, theming, and third-party integrations.\"\nlicense: MIT\nmetadata:\nauthor: claude-mods

\n

Django Unfold Admin

\n

Modern Django admin theme with Tailwind CSS, HTMX, and Alpine.js. Replaces Django's default admin with a polished, feature-rich interface.

\n

Quick Start

\n

Installation

\n
# settings.py - unfold MUST be before django.contrib.admin\nINSTALLED_APPS = [\n    \"unfold\",\n    \"unfold.contrib.filters\",          # advanced filters\n    \"unfold.contrib.forms\",            # array/wysiwyg widgets\n    \"unfold.contrib.inlines\",          # nonrelated inlines\n    \"unfold.contrib.import_export\",    # styled import/export\n    \"unfold.contrib.guardian\",         # django-guardian integration\n    \"unfold.contrib.simple_history\",   # django-simple-history integration\n    \"unfold.contrib.constance\",        # django-constance integration\n    \"unfold.contrib.location_field\",   # django-location-field integration\n    # ...\n    \"django.contrib.admin\",\n]\n
\n

Minimal Admin

\n
from unfold.admin import ModelAdmin\n\n@admin.register(MyModel)\nclass MyModelAdmin(ModelAdmin):\n    pass  # inherits Unfold styling\n
\n

Site Configuration

\n

Replace the default AdminSite or configure via UNFOLD dict in settings. See references/configuration.md for the complete settings reference.

\n
UNFOLD = {\n    \"SITE_TITLE\": \"My Admin\",\n    \"SITE_HEADER\": \"My Admin\",\n    \"SITE_SYMBOL\": \"dashboard\",  # Material Symbols icon name\n    \"SIDEBAR\": {\n        \"show_search\": True,\n        \"navigation\": [\n            {\n                \"title\": _(\"Navigation\"),\n                \"items\": [\n                    {\n                        \"title\": _(\"Dashboard\"),\n                        \"icon\": \"dashboard\",\n                        \"link\": reverse_lazy(\"admin:index\"),\n                    },\n                ],\n            },\n        ],\n    },\n}\n
\n

Core Workflow

\n

When building Unfold admin interfaces, follow this sequence:

\n
    \n
  1. Configure site - UNFOLD settings dict (branding, sidebar, theme)
    2. \n
  2. Register models - Extend unfold.admin.ModelAdmin
    3. \n
  3. Enhance display - @display decorator for list columns
    4. \n
  4. Add actions - @action decorator for row/list/detail/submit actions
    5. \n
  5. Configure filters - Replace default filters with Unfold filter classes
    6. \n
  6. Override widgets - Apply Unfold widgets via formfield_overrides
    7. \n
  7. Set up inlines - Use Unfold's inline classes with tabs, pagination, sorting
    8. \n
  8. Build dashboard - @register_component + BaseComponent for KPI cards
    9. \n
\n

ModelAdmin Attributes

\n

Unfold extends Django's ModelAdmin with these additional attributes:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
AttributeTypePurpose
list_fullwidthboolFull-width changelist (no sidebar)
list_filter_submitboolAdd submit button to filters
list_filter_sheetboolFilters in sliding sheet panel
compressed_fieldsboolCompact field spacing in forms
warn_unsaved_formboolWarn before leaving unsaved form
ordering_fieldstrField name for drag-to-reorder
hide_ordering_fieldboolHide the ordering field column
list_horizontal_scrollbar_topboolScrollbar at top of list
list_disable_select_allboolDisable \"select all\" checkbox
change_form_show_cancel_buttonboolShow cancel button on form
actions_listlistGlobal changelist actions
actions_rowlistPer-row actions in changelist
actions_detaillistActions on change form
actions_submit_linelistActions in form submit area
actions_list_hide_defaultboolHide default list actions
actions_detail_hide_defaultboolHide default detail actions
conditional_fieldsdictJS expressions for field visibility
change_form_datasetslistBaseDataset subclasses for change form
list_sectionslistTableSection/TemplateSection for list
list_sections_classesstrCSS grid classes for sections
readonly_preprocess_fieldsdictTransform readonly field content
add_fieldsetslistSeparate fieldsets for add form (like UserAdmin)
\n

Template Injection Points

\n

Insert custom HTML before/after changelist or change form:

\n
class MyAdmin(ModelAdmin):\n    # Changelist\n    list_before_template = \"myapp/list_before.html\"\n    list_after_template = \"myapp/list_after.html\"\n    # Change form (inside <form> tag)\n    change_form_before_template = \"myapp/form_before.html\"\n    change_form_after_template = \"myapp/form_after.html\"\n    # Change form (outside <form> tag)\n    change_form_outer_before_template = \"myapp/outer_before.html\"\n    change_form_outer_after_template = \"myapp/outer_after.html\"\n
\n

Conditional Fields

\n

Show/hide fields based on other field values (Alpine.js expressions):

\n
class MyAdmin(ModelAdmin):\n    conditional_fields = {\n        \"premium_features\": \"plan == 'PRO'\",\n        \"discount_amount\": \"has_discount == true\",\n    }\n
\n

Actions System

\n

Four action types, each with different signatures. See references/actions-filters.md for complete reference.

\n
from unfold.decorators import action\nfrom unfold.enums import ActionVariant\n\n# List action (no object context)\n@action(description=_(\"Rebuild Index\"), icon=\"sync\", variant=ActionVariant.PRIMARY)\ndef rebuild_index(self, request):\n    # process...\n    return redirect(request.headers[\"referer\"])\n\n# Row action (receives object_id)\n@action(description=_(\"Approve\"), url_path=\"approve\")\ndef approve_row(self, request, object_id):\n    obj = self.model.objects.get(pk=object_id)\n    return redirect(request.headers[\"referer\"])\n\n# Detail action (receives object_id, shown on change form)\n@action(description=_(\"Send Email\"), permissions=[\"send_email\"])\ndef send_email(self, request, object_id):\n    return redirect(reverse_lazy(\"admin:myapp_mymodel_change\", args=[object_id]))\n\n# Submit line action (receives obj instance, runs on save)\n@action(description=_(\"Save & Publish\"))\ndef save_and_publish(self, request, obj):\n    obj.published = True\n
\n

Action Groups (Dropdown Menus)

\n
actions_list = [\n    \"primary_action\",\n    {\n        \"title\": _(\"More\"),\n        \"variant\": ActionVariant.PRIMARY,\n        \"items\": [\"secondary_action\", \"tertiary_action\"],\n    },\n]\n
\n

Permissions

\n
@action(permissions=[\"can_export\", \"auth.view_user\"])\ndef export_data(self, request):\n    pass\n\ndef has_can_export_permission(self, request):\n    return request.user.is_superuser\n
\n

Display Decorator

\n

Enhance list_display columns. See references/actions-filters.md.

\n
from unfold.decorators import display\n\n# Colored status labels\n@display(description=_(\"Status\"), ordering=\"status\", label={\n    \"active\": \"success\",    # green\n    \"pending\": \"info\",      # blue\n    \"warning\": \"warning\",   # orange\n    \"inactive\": \"danger\",   # red\n})\ndef show_status(self, obj):\n    return obj.status\n\n# Rich header with avatar\n@display(description=_(\"User\"), header=True)\ndef show_header(self, obj):\n    return [\n        obj.full_name,           # primary text\n        obj.email,               # secondary text\n        obj.initials,            # badge text\n        {\"path\": obj.avatar.url, \"width\": 24, \"height\": 24, \"borderless\": True},\n    ]\n\n# Interactive dropdown\n@display(description=_(\"Teams\"), dropdown=True)\ndef show_teams(self, obj):\n    return {\n        \"title\": f\"{obj.teams.count()} teams\",\n        \"items\": [{\"title\": t.name, \"link\": t.get_admin_url()} for t in obj.teams.all()],\n        \"striped\": True,\n        \"max_height\": 200,\n    }\n\n# Boolean checkmark\n@display(description=_(\"Active\"), boolean=True)\ndef is_active(self, obj):\n    return obj.is_active\n
\n

Filters

\n

Unfold provides advanced filter classes. See references/actions-filters.md.

\n
from unfold.contrib.filters.admin import (\n    TextFilter, RangeNumericFilter, RangeDateFilter, RangeDateTimeFilter,\n    SingleNumericFilter, SliderNumericFilter, RelatedDropdownFilter,\n    RelatedCheckboxFilter, ChoicesCheckboxFilter, AllValuesCheckboxFilter,\n    BooleanRadioFilter, CheckboxFilter, AutocompleteSelectMultipleFilter,\n)\n\nclass MyAdmin(ModelAdmin):\n    list_filter_submit = True  # required for input-based filters\n    list_filter = [\n        (\"salary\", RangeNumericFilter),\n        (\"status\", ChoicesCheckboxFilter),\n        (\"created_at\", RangeDateFilter),\n        (\"category\", RelatedDropdownFilter),\n        (\"is_active\", BooleanRadioFilter),\n    ]\n
\n

Custom Text Filter

\n
class NameFilter(TextFilter):\n    title = _(\"Name\")\n    parameter_name = \"name\"\n\n    def queryset(self, request, queryset):\n        if self.value() in EMPTY_VALUES:\n            return queryset\n        return queryset.filter(name__icontains=self.value())\n
\n

Widgets

\n

Override form widgets for Unfold styling. See references/widgets-inlines.md.

\n
from unfold.widgets import (\n    UnfoldAdminTextInputWidget, UnfoldAdminSelectWidget, UnfoldAdminSelect2Widget,\n    UnfoldBooleanSwitchWidget, UnfoldAdminColorInputWidget,\n    UnfoldAdminSplitDateTimeWidget, UnfoldAdminImageFieldWidget,\n)\nfrom unfold.contrib.forms.widgets import WysiwygWidget, ArrayWidget\n\nclass MyAdmin(ModelAdmin):\n    formfield_overrides = {\n        models.TextField: {\"widget\": WysiwygWidget},\n        models.ImageField: {\"widget\": UnfoldAdminImageFieldWidget},\n    }\n
\n

Text Input with Icons

\n
widget = UnfoldAdminTextInputWidget(attrs={\n    \"prefix_icon\": \"search\",\n    \"suffix_icon\": \"euro\",\n})\n
\n

Inlines

\n

Unfold inlines support tabs, pagination, sorting, and nonrelated models. See references/widgets-inlines.md.

\n
from unfold.admin import TabularInline, StackedInline\nfrom unfold.contrib.inlines.admin import NonrelatedStackedInline\n\nclass OrderItemInline(TabularInline):\n    model = OrderItem\n    tab = True          # show as tab\n    per_page = 10       # paginated\n    ordering_field = \"weight\"  # drag-to-reorder\n    hide_title = True\n    collapsible = True\n
\n

Fieldset Tabs

\n

Group fieldsets into tabs using \"classes\": [\"tab\"]:

\n
fieldsets = [\n    (None, {\"fields\": [\"name\", \"email\"]}),  # always visible\n    (_(\"Profile\"), {\"classes\": [\"tab\"], \"fields\": [\"bio\", \"avatar\"]}),\n    (_(\"Settings\"), {\"classes\": [\"tab\"], \"fields\": [\"theme\", \"notifications\"]}),\n]\n
\n

Dashboard Components

\n

Build KPI cards and custom dashboard widgets. See references/dashboard.md.

\n
from unfold.components import BaseComponent, register_component\nfrom django.template.loader import render_to_string\n\n@register_component\nclass ActiveUsersComponent(BaseComponent):\n    def get_context_data(self, **kwargs):\n        context = super().get_context_data(**kwargs)\n        context[\"children\"] = render_to_string(\"myapp/kpi_card.html\", {\n            \"total\": User.objects.filter(is_active=True).count(),\n            \"label\": \"Active Users\",\n        })\n        return context\n
\n

Configure in settings:

\n
UNFOLD = {\n    \"DASHBOARD_CALLBACK\": \"myapp.views.dashboard_callback\",\n}\n
\n

Sections (Changelist Panels)

\n

Embed related data panels in changelist views:

\n
from unfold.sections import TableSection, TemplateSection\n\nclass RecentOrdersSection(TableSection):\n    related_name = \"order_set\"\n    fields = [\"id\", \"total\", \"status\"]\n    height = 380\n\nclass ChartSection(TemplateSection):\n    template_name = \"myapp/chart.html\"\n\nclass MyAdmin(ModelAdmin):\n    list_sections = [RecentOrdersSection, ChartSection]\n    list_sections_classes = \"lg:grid-cols-2\"\n
\n

Datasets (Change Form Panels)

\n

Embed model listings within change forms:

\n
from unfold.datasets import BaseDataset\n\nclass RelatedItemsDatasetAdmin(ModelAdmin):\n    list_display = [\"name\", \"status\"]\n    search_fields = [\"name\"]\n\nclass RelatedItemsDataset(BaseDataset):\n    model = RelatedItem\n    model_admin = RelatedItemsDatasetAdmin\n    tab = True  # show as tab\n\nclass MyAdmin(ModelAdmin):\n    change_form_datasets = [RelatedItemsDataset]\n
\n

Paginator

\n

Use infinite scroll pagination:

\n
from unfold.paginator import InfinitePaginator\n\nclass MyAdmin(ModelAdmin):\n    paginator = InfinitePaginator\n    show_full_result_count = False\n    list_per_page = 20\n
\n

Third-Party Integrations

\n

Unfold provides styled wrappers for common Django packages. See references/resources.md for complete setup guides.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PackageUnfold ModuleSetup
django-import-exportunfold.contrib.import_exportUse ImportForm, ExportForm, SelectableFieldsExportForm
django-guardianunfold.contrib.guardianStyled guardian integration
django-simple-historyunfold.contrib.simple_historyStyled history integration
django-constanceunfold.contrib.constanceStyled constance config
django-location-fieldunfold.contrib.location_fieldLocation widget
django-modeltranslationCompatibleMix TabbedTranslationAdmin with ModelAdmin
django-celery-beatCompatible (rewire)Unregister 5 models, re-register with Unfold
django-moneyunfold.widgetsUnfoldAdminMoneyWidget
djangoqlCompatibleMix DjangoQLSearchMixin with ModelAdmin
django-crispy-formsCompatibleUnfold template pack available
\n
# Multiple inheritance - Unfold ModelAdmin always last\n@admin.register(MyModel)\nclass MyAdmin(DjangoQLSearchMixin, SimpleHistoryAdmin, GuardedModelAdmin, ModelAdmin):\n    pass\n
\n

Built-In Template Components

\n

Unfold ships reusable template components for dashboards and custom pages:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ComponentPathKey Variables
Cardunfold/components/card.htmltitle, footer, label, icon
Bar Chartunfold/components/chart/bar.htmldata (JSON), height, width
Line Chartunfold/components/chart/line.htmldata (JSON), height, width
Progressunfold/components/progress.htmlvalue, title, description
Tableunfold/components/table.htmltable, card_included, striped
Buttonunfold/components/button.htmlname, href, submit
Trackerunfold/components/tracker.htmldata
Cohortunfold/components/cohort.htmldata
\n
{% load unfold %}\n{% component \"MyKPIComponent\" %}{% endcomponent %}\n
\n

User Admin Forms

\n

Unfold provides styled versions of Django's auth admin forms:

\n
from unfold.forms import AdminPasswordChangeForm, UserChangeForm, UserCreationForm\n\n@admin.register(User)\nclass UserAdmin(BaseUserAdmin, ModelAdmin):\n    form = UserChangeForm\n    add_form = UserCreationForm\n    change_password_form = AdminPasswordChangeForm\n
\n

Reference Files

\n

Detailed documentation split by topic:

\n\n

Read the relevant reference file when you need detailed configuration options, the full list of available classes, complete code examples, or integration setup guides for a specific feature area.

\n

Key External References

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ResourceURL
Docshttps://unfoldadmin.com/docs/
GitHubhttps://github.com/unfoldadmin/django-unfold
Demo App (Formula)https://github.com/unfoldadmin/formula
Live Demohttps://demo.unfoldadmin.com
Material Symbols (Icons)https://fonts.google.com/icons
\n

When uncertain about an implementation pattern, consult formula/admin.py and formula/settings.py in the Formula demo repo - it covers virtually every Unfold feature.

\n","files":[{"path":"references/actions-filters.md","sizeBytes":13880,"isText":true},{"path":"references/configuration.md","sizeBytes":12203,"isText":true},{"path":"references/dashboard.md","sizeBytes":10390,"isText":true},{"path":"references/resources.md","sizeBytes":17394,"isText":true},{"path":"references/widgets-inlines.md","sizeBytes":16040,"isText":true},{"path":"SKILL.md","sizeBytes":17019,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-30T19:39:30.554276Z","sha256":"F3B20661F18C34722F065A42B91A1151FD9941BCBEAB63A75A441839FBAF3E35","sizeBytes":28937},"review":null,"source":{"repositoryUrl":"https://github.com/0xDarkMatter/claude-mods","path":"skills/unfold-admin","license":"MIT","commit":"3dfaf0ba5753026a99ee13f9d9ed56b9793bb6e8","subtreeSha":"A35FDBD6ED4B73DFACBB31A4F798912E883D9D8D322445F306CE03CEE9ECD009","lastSyncedAt":"2026-09-30T19:37:28.226022Z"},"reviewedAt":"2026-09-30T19:43:58.007559Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/0xDarkMatter/claude-mods/tree/main/skills/unfold-admin"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install 0xdarkmatter-claude-mods@llmmart"},{"target":"git","command":"git clone https://github.com/0xDarkMatter/claude-mods.git"}]}