Unfold Admin

https://unfoldadmin.com/docs
Admin
Unfold Admin is a modern Django admin theme that provides pre-built dashboards, customizable...
Tokens:60,533
Snippets:449
Trust Score:7.2
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install Tailwind CSS and CLI

Source: https://unfoldadmin.com/docs/styles-scripts/customizing-tailwind

Install Tailwind CSS and its CLI tool using npm. Required for compiling Tailwind styles.

```bash
npm i tailwindcss @tailwindcss/cli

```

--------------------------------

### Install and run pre-commit hooks

Source: https://unfoldadmin.com/docs/development

Install pre-commit and its hooks, including the commit-msg hook, then run all checks. Recommended before adding source code to catch potential issues.

```bash
pip install pre-commit
pre-commit install
pre-commit install --hook-type commit-msg
pre-commit run --all-files # Check if everything is okay

```

--------------------------------

### Install jsonschema package

Source: https://unfoldadmin.com/docs/fields/jsonschemafield

Install the optional `jsonschema` package to enable backend validation for JSONSchemaField. Without it, validation will not work.

```bash
uv add jsonschema

```

--------------------------------

### Install django-crispy-forms with pip, uv, or poetry

Source: https://unfoldadmin.com/docs/configuration/crispy-forms

Install django-crispy-forms using your preferred package manager. The commands are alternatives; choose one.

```bash
pip install django-crispy-forms
```

```bash
uv add django-crispy-forms
```

```bash
poetry add django-crispy-forms
```

--------------------------------

### Minimal URL configuration in urls.py

Source: https://unfoldadmin.com/docs/installation

The default admin URL configuration works with Unfold. This example shows the minimal setup with the admin site at /admin/.

```python
# urls.py

from django.contrib import admin
from django.urls import path

urlpatterns = [
    path("admin/", admin.site.urls),
    # Other URL paths
]

```

--------------------------------

### Installation: Add unfold and unfold.contrib.forms to INSTALLED_APPS

Source: https://unfoldadmin.com/docs/widgets/array

Required Django settings to enable the Unfold ArrayWidget. Add both 'unfold' and 'unfold.contrib.forms' to INSTALLED_APPS.

```python
# settings.py

INSTALLED_APPS = [
    "unfold",
    "unfold.contrib.forms",
]

```

--------------------------------

### UNFOLD settings dictionary in settings.py

Source: https://unfoldadmin.com/docs/configuration

Complete example of the UNFOLD dictionary for Django settings, showing all available configuration options. Use this as a reference to customize the admin interface. The example includes commented-out alternatives for SITE_ICON and SITE_LOGO, and shows both light/dark mode variants.

```python
# settings.py

from django.templatetags.static import static
from django.urls import reverse_lazy
from django.utils.translation import gettext_lazy as _

UNFOLD = {
    "SITE_TITLE": "Custom suffix in <title> tag",
    "SITE_HEADER": "Appears in sidebar at the top",
    "SITE_SUBHEADER": "Appears under SITE_HEADER",
    "SITE_VERSION": "0.1.0",
    "SITE_DROPDOWN": [
        {
            "icon": "diamond",
            "title": _("My site"),
            "link": "https://example.com",
        },
        # ...
    ],
    "SITE_URL": "/",
    "SITE_VIEWS": [
        ("some-path-to-view", "name_of_view_1", "path.to.view_itself_1"),
        ("other-path-to-view", "another_name_of_view_2", "path.to.view_itself_2"),
    ],
    # "SITE_ICON": lambda request: static("icon.svg"),  # both modes, optimise for 32px height
    "SITE_ICON": {
        "light": lambda request: static("icon-light.svg"),  # light mode
        "dark": lambda request: static("icon-dark.svg"),  # dark mode
    },
    # "SITE_LOGO": lambda request: static("logo.svg"),  # both modes, optimise for 32px height
    "SITE_LOGO": {
        "light": lambda request: static("logo-light.svg"),  # light mode
        "dark": lambda request: static("logo-dark.svg"),  # dark mode
    },
    "SITE_SYMBOL": "speed",  # symbol from icon set
    "SITE_FAVICONS": [
        {
            "rel": "icon",
            "sizes": "32x32",
            "type": "image/svg+xml",
            "href": lambda request: static("favicon.svg"),
        },
    ],
    "SHOW_HISTORY": True,  # show/hide "History" button, default: True
    "SHOW_VIEW_ON_SITE": True,  # show/hide "View on site" button, default: True
    "SHOW_BACK_BUTTON": False,  # show/hide "Back" button on changeform in header, default: False
    "SHOW_UI_WARNINGS": False,  # show/hide warnings in UI, default: False
    "ENVIRONMENT": "sample_app.environment_callback",  # environment name in header
    "ENVIRONMENT_TITLE_PREFIX": "sample_app.environment_title_prefix_callback",  # environment name prefix in title tag
    "DASHBOARD_CALLBACK": "sample_app.dashboard_callback",
    "THEME": "dark",  # Force theme: "dark" or "light". Will disable theme switcher
    "LOGIN": {
        "image": lambda request: static("sample/login-bg.jpg"),
        "redirect_after": lambda request: reverse_lazy("admin:APP_MODEL_changelist"),
        # Inherits from `unfold.forms.AuthenticationForm`
        "form": "app.forms.CustomLoginForm",
    },
    "STYLES": [
        lambda request: static("css/style.css"),
    ],
    "SCRIPTS": [
        lambda request: static("js/script.js"),
    ],
    "BORDER_RADIUS": "6px",
    "COLORS": {
        "base": {
            "50": "oklch(98.5% .002 247.839)",
            "100": "oklch(96.7% .003 264.542)",
            "200": "oklch(92.8% .006 264.531)",
            "300": "oklch(87.2% .01 258.338)",
            "400": "oklch(70.7% .022 261.325)",
            "500": "oklch(55.1% .027 264.364)",
            "600": "oklch(44.6% .03 256.802)",
            "700": "oklch(37.3% .034 259.733)",
            "800": "oklch(27.8% .033 256.848)",
            "900": "oklch(21% .034 264.665)",
            "950": "oklch(13% .028 261.692)",
        },
        "primary": {
            "50": "oklch(97.7% .014 308.299)",
            "100": "oklch(94.6% .033 307.174)",
            "200": "oklch(90.2% .063 306.703)",
            "300": "oklch(82.7% .119 306.383)",
            "400": "oklch(71.4% .203 305.504)",
            "500": "oklch(62.7% .265 303.9)",
            "600": "oklch(55.8% .288 302.321)",
            "700": "oklch(49.6% .265 301.924)",
            "800": "oklch(43.8% .218 303.724)",
            "900": "oklch(38.1% .176 304.987)",
            "950": "oklch(29.1% .149 302.717)",
        },
        "font": {
            "subtle-light": "var(--color-base-500)",  # text-base-500
            "subtle-dark": "var(--color-base-400)",  # text-base-400
            "default-light": "var(--color-base-600)",  # text-base-600
            "default-dark": "var(--color-base-300)",  # text-base-300
            "important-light": "var(--color-base-900)",  # text-base-900
            "important-dark": "var(--color-base-100)",  # text-base-100
        },
    },
    "SIDEBAR": {
        "show_search": False,  # Search in applications and models names
        "show_all_applications": False,  # Dropdown with all applications and models
        "navigation": [
            {

```

--------------------------------

### INSTALLED_APPS configuration for django-reversion-compare

Source: https://unfoldadmin.com/docs/integrations/django-reversion-compare

Add 'unfold.contrib.reversion_compare' to INSTALLED_APPS before 'reversion_compare' to load Unfold's templates. Ensure django-reversion is installed and configured first.

```python
INSTALLED_APPS = [
    "unfold.contrib.reversion",
    "unfold.contrib.reversion_compare",  # Add this to load new templates
    # ...
    "reversion",
    "reversion_compare",
]

```

--------------------------------

### Install django-unfold with pip, uv, or poetry

Source: https://unfoldadmin.com/docs/installation

Install the django-unfold package using your preferred Python package manager. Choose one command based on your environment.

```bash
pip install django-unfold
uv add django-unfold
poetry add django-unfold

```

--------------------------------

### Data structure example

Source: https://unfoldadmin.com/docs/components/tracker

Example data structure for the tracker component. Each item can have optional color, tooltip, href, and class attributes.

```python
DATA = [
    {
        # Optional: configure custom color for the item
        "color": "bg-primary-400 dark:bg-primary-700",
        # Optional: will show a tooltip on hover
        "tooltip": "Custom value 1",
        # Optional: will make the item a link
        "href": "https://example.com",
        # Optional: add custom CSS classes to the item
        "class": "custom-class",
    },
    {
        "color": "bg-primary-400 dark:bg-primary-700",
        "tooltip": "Custom value 2",
    },
]

```

--------------------------------

### Run tests with pytest

Source: https://unfoldadmin.com/docs/development

Run the test suite from the repository root. The tests will execute in the tests directory. No manual dependency installation is needed because uv handles dependencies automatically.

```bash
uv run -- pytest .

```

--------------------------------

### Install Tailwind CLI on macOS with Homebrew

Source: https://unfoldadmin.com/docs/development

Install the standalone tailwindcss CLI on macOS using Homebrew. Required before compiling Tailwind CSS for Unfold.

```bash
brew install tailwindcss

```

--------------------------------

### Add unfold.contrib.hijack to INSTALLED_APPS

Source: https://unfoldadmin.com/docs/integrations/django-hijack

Add 'unfold.contrib.hijack' to INSTALLED_APPS in settings.py to load the new templates that enhance the styling of impersonation notifications and user changelist buttons. This is required after installing django-hijack.

```python
# settings.py

INSTALLED_APPS = [
    "unfold.contrib.hijack",  # Add this to load new templates
]

```

--------------------------------

### Configure autocomplete filters in admin.py

Source: https://unfoldadmin.com/docs/filters/autocomplete

Example admin configuration showing how to use AutocompleteSelectFilter and AutocompleteSelectMultipleFilter in list_filter. Requires the fields to be ForeignKey or ManyToManyField and the referenced admin model to have search_fields defined.

```python
# admin.py

from django.contrib import admin
from django.contrib.auth.models import User

from unfold.admin import ModelAdmin
from unfold.contrib.filters.admin import (
    AutocompleteSelectFilter,
    AutocompleteSelectMultipleFilter,
)


@admin.register(User)
class YourModelAdmin(ModelAdmin):
    list_filter = (
        # Autocomplete filter
        ["other_model_field", AutocompleteSelectFilter],
        # Autocomplete multiple filter
        ["other_multiple_model_field", AutocompleteSelectMultipleFilter],
    )


class OtherModelAdmin(ModelAdmin):
    search_fields = ["name"]
```

--------------------------------

### Create autocomplete view and form fields

Source: https://unfoldadmin.com/docs/fields/autocomplete

Complete example showing how to create a custom autocomplete view subclassing BaseAutocompleteView, register it in ModelAdmin via custom_urls, and use UnfoldAdminAutocompleteModelChoiceField and UnfoldAdminMultipleAutocompleteModelChoiceField in a form. The view returns JSON options and includes permission checks and search filtering.

```python
from django import forms
from django.contrib import admin
from django.utils.translation import gettext_lazy as _

from unfold.admin import ModelAdmin
from unfold.views import BaseAutocompleteView
from unfold.fields import (
    UnfoldAdminAutocompleteModelChoiceField,
    UnfoldAdminMultipleAutocompleteModelChoiceField,
)

from .models import MyModel


# Custom ListView returning JSON with available select options
class MyAutocompleteView(BaseAutocompleteView):
    model = MyModel

    def dispatch(self, request, *args, **kwargs):
        # Permissions checks here
        return super().dispatch(request, *args, **kwargs)

    def get_queryset(self):
        # Search query is available in the request.GET object under the key "term"
        term = self.request.GET.get("term")

        # Additional filters and permissions checks here
        qs = super().get_queryset()

        # No search provided, return all results
        if term == "":
            return qs

        # Search query provided, filter results
        return qs.filter(my_field__icontains=term)


@admin.register(MyModel)
class MyModelAdmin(ModelAdmin):
    # Register custom ListView above
    custom_urls = (
        (
            "autocomplete-url-path",
            "custom_autocomplete_path_name",
            MyAutocompleteView.as_view(),
        ),
    )


class MyForm(forms.Form):
    one_object = UnfoldAdminAutocompleteModelChoiceField(
        label=_("Object - Single value"),
        # Important for validation. Make sure it offers same results as the custom view
        queryset=MyModel.objects.all(),
        # Map autocomplete results to the custom view
        url_path="admin:custom_autocomplete_path_name",
    )
    multiple_objects = UnfoldAdminMultipleAutocompleteModelChoiceField(
        label=_("Objects - Multiple values"),
        queryset=MyModel.objects.all(),
        url_path="admin:custon_autocomplete_path_name",
    )
```

--------------------------------

### Add unfold.contrib.reversion to INSTALLED_APPS

Source: https://unfoldadmin.com/docs/integrations/django-reversion

Add 'unfold.contrib.reversion' to INSTALLED_APPS in settings.py, before 'reversion', so Unfold's templates are loaded first. This is the only step required to get django-reversion support in the Unfold admin interface.

```python
INSTALLED_APPS = [
    "unfold.contrib.reversion",  # Add this to load new templates
    # ...
    "reversion",
]

```

--------------------------------

### Define and register Unfold inlines in admin.py

Source: https://unfoldadmin.com/docs/inlines/introduction

Shows how to import Unfold's StackedInline and TabularInline classes and define custom inline classes for a model. The example registers a UserAdmin with both inlines, using Unfold's classes instead of Django's native ones for better styling.

```python
# admin.py

from django.contrib import admin
from django.contrib.auth.models import User
from unfold.admin import StackedInline, TabularInline


class MyStackedInline(StackedInline):
    model = User


class MyTabularInline(TabularInline):
    model = User


@admin.register(User)
class UserAdmin(ModelAdmin):
    inlines = [MyStackedInline, MyTabularInline]

```

--------------------------------

### Build custom tabs navigation in tabs_callback function

Source: https://unfoldadmin.com/docs/tabs/dynamic

Example of a callback function that returns a list of tab dictionaries. Uses the request object to build the structure. Includes 'page' identifier, 'models' for changeform views, and 'items' with title, link, active flag, and optional inline fragment URL.

```python
# admin.py

from django.http import HttpRequest


def tabs_callback(request: HttpRequest) -> list[dict[str, Any]]:
    return (
        [
            {
                # Unique tab identifier to render tabs in custom templates
                "page": "custom_page",
                # Applies for the changeform view
                "models": [
                    {"name": "app_label.model_name_in_lowercase", "detail": True},
                ],
                "items": [
                    {
                        "title": _("Your custom title"),
                        "link": reverse_lazy("admin:app_label_model_name_changelist"),
                        "active": True,  # Configure active tab
                        # "active": lambda request: True
                    },
                    {
                        "title": _("Inline tab"),
                        "link": reverse_lazy("admin:app_label_model_name_changelist"),
                        "inline": "corresponding-fragment-url",
                    },
                ],
            },
        ],
    )

```

--------------------------------

### settings.py: Enable multi-language support

Source: https://unfoldadmin.com/docs/configuration/multi-language

Add LocaleMiddleware to MIDDLEWARE, set LANGUAGE_CODE to 'en', enable USE_I18N, and define LANGUAGES with German and English. This prepares the admin for language switching.

```python
# settings.py

MIDDLEWARE = [
    "django.middleware.locale.LocaleMiddleware",
]

LANGUAGE_CODE = "en"

USE_I18N = True

LANGUAGES = (
    ("de", _("German")),
    ("en", _("English")),
)

```

--------------------------------

### Create custom admin site with UnfoldAdminSite

Source: https://unfoldadmin.com/docs/configuration/custom-sites

Defines a custom admin site by subclassing `unfold.sites.UnfoldAdminSite` in `sites.py`. This is the first step to create a custom admin site.

```python
# sites.py

from django.contrib import admin
from unfold.sites import UnfoldAdminSite


class CustomAdminSite(UnfoldAdminSite):
    pass


custom_admin_site = CustomAdminSite(name="custom_admin_site")

```

--------------------------------

### Optimize queryset for autocomplete field

Source: https://unfoldadmin.com/docs/fields/autocomplete

Shows how to override the queryset of UnfoldAdminAutocompleteModelChoiceField to avoid loading the full queryset on GET requests. For GET requests, it uses an empty queryset unless initial values are present; for POST requests, it filters to selected choices. The request argument must be manually passed, e.g., via get_form_kwargs in FormView.

```python
class MyAutocompleteView(BaseAutocompleteView):
    one_object = UnfoldAdminAutocompleteModelChoiceField(
        label=_("Object - Single value"),
        queryset=MyModel.objects.all(),
        url_path="admin:custom_autocomplete_path_name",
    )

    def __init__(self, request, *args, **kwargs):
        # The request argument needs to be manually passed. If you are using
        # `FormView` just use `get_form_kwargs` to pass the request argument.

        if request.method == "GET":
            if "initial" in kwargs:
                # Initial values are present
                self.queryset = MyModel.objects.filter(pk__in=kwargs["initial"]
            else:

                self.queryset = MyModel.objects.none()
        elif request.method == "POST":
            self.queryset = MyModel.objects.filter(pk__in=request.POST.getlist("objects"))

        super().__init__(request, *args, **kwargs)
```

--------------------------------

### Inherit from unfold.admin.ModelAdmin in admin.py

Source: https://unfoldadmin.com/docs/installation

Admin classes must inherit from unfold.admin.ModelAdmin instead of django.contrib.admin.ModelAdmin to get styled forms and full Unfold functionality.

```python
# admin.py

from django.contrib import admin
from unfold.admin import ModelAdmin


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

```

--------------------------------

### Admin example inheriting from SimpleHistoryAdmin and ModelAdmin

Source: https://unfoldadmin.com/docs/integrations/django-simple-history

Register a model admin that inherits from both SimpleHistoryAdmin and unfold.admin.ModelAdmin to combine history tracking with Unfold's styling.

```python
# admin.py

from django.contrib import admin
from django.contrib.auth import get_user_model

from simple_history.admin import SimpleHistoryAdmin
from unfold.admin import ModelAdmin

User = get_user_model()


@admin.register(User)
class UserAdmin(SimpleHistoryAdmin, ModelAdmin):
    pass

```

--------------------------------

### settings.py: Override language options

Source: https://unfoldadmin.com/docs/configuration/multi-language

Customize the language selector by providing a hardcoded list of languages, a callback, or custom actions. The callback example is commented out.

```python
from django.utils.translation import get_language_info

UNFOLD = {
    "LANGUAGES": {
        # Hardcoded list of languages
        "navigation": [
            {
                "bidi": False,
                "code": "de",
                "name": "German",
                "name_local": "Deutsch",
                "name_translated": "German",
            },
        ],
        # Using a callback to generate list of languages
        # "navigation": "your_app.utils.languages_callback",
        # In case you want to have some custom form handling
        # "actions": reverse_lazy("custom_form_submit")
    }
}

# def languages_callback(request):
#     return [get_language_info(lang) for lang in ["en", "de", "fr"]]

```

--------------------------------

### Compile Tailwind styles with CLI

Source: https://unfoldadmin.com/docs/styles-scripts/customizing-tailwind

Compile the styles.css file into a minified CSS output using the Tailwind CLI.

```bash
npx @tailwindcss/cli -i styles.css -o your_project/static/css/styles.css --minify

```

--------------------------------

### Override default admin site with BasicAppConfig

Source: https://unfoldadmin.com/docs/configuration/custom-sites

Configures `INSTALLED_APPS` to use `unfold.apps.BasicAppConfig` instead of `unfold` when overriding the default admin site. This is necessary to avoid conflicts with the default admin site.

```python
# settings.py

INSTALLED_APPS = [
    "unfold.apps.BasicAppConfig",  # App config not overriding `django.contrib.admin.site`
    # some other apps
    "django.contrib.admin",
    "your_app",
]

```

--------------------------------

### Create class-based view with UnfoldModelAdminViewMixin and FormView in views.py

Source: https://unfoldadmin.com/docs/configuration/crispy-forms

Define a view that inherits from UnfoldModelAdminViewMixin and FormView, set the form_class, permissions, and template. Must be registered as a custom page in admin.

```python
# views.py

from django.views.generic import FormView

from unfold.views import UnfoldModelAdminViewMixin

from .forms import CustomForm


class MyClassBasedView(UnfoldModelAdminViewMixin, FormView):
    title = "Custom Title"
    form_class = CustomForm
    success_url = reverse_lazy("admin:index")
    permission_required = (
        "app_name.add_model_name",
        "app_name.change_model_name",
    )
    template_name = "app_name/some_template.html"

```

--------------------------------

### Hide built-in actions with actions_list_hide_default

Source: https://unfoldadmin.com/docs/actions/introduction

Set actions_list_hide_default to True to hide default actions and display only custom actions. The example defines a custom action 'existing_action_wrapper' that redirects to an external URL.

```python
from django.utils.translation import gettext_lazy as _
from django.shortcuts import redirect

from unfold.admin import ModelAdmin
from unfold.decorators import action


class MyAdmin(ModelAdmin):
    actions_list = ["my_action", "existing_action_wrapper"]
    actions_list_hide_default = True

    @action(description=_("History"), icon="history")
    def existing_action_wrapper(self, *args, **kwargs):
        # Redirect to the page URL which is created by third-party package
        return redirect("https://example.com")

```

--------------------------------

### settings.py: Enable language selector

Source: https://unfoldadmin.com/docs/configuration/multi-language

Add UNFOLD = {"SHOW_LANGUAGES": True,} to settings.py to display the language selector in the top right corner of the admin.

```python
# settings.py

UNFOLD = {
    "SHOW_LANGUAGES": True,
}

```

--------------------------------

### @action decorator with icon parameter

Source: https://unfoldadmin.com/docs/actions

Shows how to set an icon for an action using the icon parameter in the @action decorator.

```APIDOC
## @action(description="Custom action", icon="person")

### Description
Sets a custom icon for an action using the `icon` parameter in the `@action` decorator.

### Parameters
- **description** (string) - Required - Description of the action.
- **icon** (string) - Required - Icon identifier for the action.

### Example
```python
from django.db.models import QuerySet
from django.http import HttpRequest

from unfold.decorators import action


@action(description="Custom action", icon="person")
def custom_action(self, request: HttpRequest, queryset: QuerySet):
    pass
```
```

--------------------------------

### Compile Tailwind CSS for Unfold

Source: https://unfoldadmin.com/docs/development

Compile the Tailwind CSS stylesheet from the source file to the static output file with minification and watch mode. Run from the project root after installing the tailwindcss CLI.

```bash
tailwindcss -i src/unfold/styles.css -o src/unfold/static/unfold/css/styles.css --minify --watch

```

--------------------------------

### Create a custom class-based view and register it in admin URLs

Source: https://unfoldadmin.com/docs/configuration/custom-pages

Define a class-based view inheriting from UnfoldModelAdminViewMixin and TemplateView, set required title and permission_required properties, and add a URL pattern in the admin's get_urls method. The view must be wrapped with admin_site.admin_view and passed model_admin.

```python
# admin.py

from django.urls import path
from django.views.generic import TemplateView

from unfold.admin import ModelAdmin
from unfold.views import UnfoldModelAdminViewMixin

from .models import MyModel


class MyClassBasedView(UnfoldModelAdminViewMixin, TemplateView):
    title = "Custom Title"  # required: custom page header title
    permission_required = ()  # required: tuple of permissions
    template_name = "some/template/path.html"


@admin.register(MyModel)
class CustomAdmin(ModelAdmin):
    def get_urls(self):
        # IMPORTANT: model_admin is required
        custom_view = self.admin_site.admin_view(
            MyClassBasedView.as_view(model_admin=self)
        )

        return super().get_urls() + [
            path("custom-url-path", custom_view, name="custom_name"),
        ]

```

--------------------------------

### Configure CONSTANCE_ADDITIONAL_FIELDS with Unfold

Source: https://unfoldadmin.com/docs/integrations/django-constance

Adds Unfold's additional field types to CONSTANCE_ADDITIONAL_FIELDS and shows an example choice_field configuration using UnfoldAdminSelectWidget. Place 'unfold.contrib.constance' before 'constance' in INSTALLED_APPS to load proper templates.

```python
# settings.py

from unfold.contrib.constance.settings import UNFOLD_CONSTANCE_ADDITIONAL_FIELDS


CONSTANCE_ADDITIONAL_FIELDS = {
    **UNFOLD_CONSTANCE_ADDITIONAL_FIELDS,
    # Example field configuration for select with choices. Not needed.
    "choice_field": [
        "django.forms.fields.ChoiceField",
        {
            "widget": "unfold.widgets.UnfoldAdminSelectWidget",
            "choices": (
                ("light-blue", "Light blue"),
                ("dark-blue", "Dark blue"),
            ),
        },
    ],
}

```

--------------------------------

### Create styles.css with Tailwind import

Source: https://unfoldadmin.com/docs/styles-scripts/customizing-tailwind

Create a styles.css file with a single import statement to configure Tailwind 4.

```css
/* styles.css */
@import 'tailwindcss';

```

--------------------------------

### Custom tracker data preparation in component class

Source: https://unfoldadmin.com/docs/components/tracker

Define a component class that prepares data for the tracker. The get_context_data method updates the context with the data and an optional size parameter ("md" or "sm").

```python
# admin.py

from unfold.components import BaseComponent, register_component


@register_component
class MyTrackerComponent(BaseComponent):
    def get_context_data(self, **kwargs):
        context = super().get_context_data(**kwargs)
        context.update({
            "data": DATA
            "size": "md", # Optional: size of tracker: "md", "sm"
        })
        return context

```

--------------------------------

### Template for custom page extending Unfold base layout

Source: https://unfoldadmin.com/docs/configuration/custom-pages

Template that extends admin/base.html and uses the content block to display custom content. It includes an example using the tab_list helper and a translation tag.

```django-html
{% extends "admin/base.html" %}

{% load admin_urls i18n unfold %}

{% block content %}
    {% tab_list "drivers" %}

    {% trans "Custom page" %}
{% endblock %}

```

--------------------------------

### Create PrettyJSONEncoder for JSON formatting

Source: https://unfoldadmin.com/docs/fields/json

Define a custom JSON encoder that formats JSON with indent=4 and sort_keys=True. This encoder is used to automatically format JSON data when saving to the database, even without Pygments installed.

```python
# encoders.py

import json


class PrettyJSONEncoder(json.JSONEncoder):
    def __init__(self, *args, indent, sort_keys, **kwargs):
        super().__init__(*args, indent=4, sort_keys=True, **kwargs)

```

--------------------------------

### Optimize queries with list_per_page and prefetch_related

Source: https://unfoldadmin.com/docs/configuration/sections

Shows two solutions for reducing queries on changelist pages with TableSection: setting list_per_page to 20 as a quick fix, and overriding get_queryset to use prefetch_related on related fields for optimal performance.

```python
from unfold.admin import ModelAdmin

from .models import SomeModel


@admin.register(SomeModel)
class SomeAdmin(ModelAdmin):
    list_per_page = 20  # Quick solution
    list_sections = [CustomTableSection]

    # Custom queryset prefetching related records
    def get_queryset(self, request):
        return (
            super()
            .get_queryset(request)
            .prefetch_related(
                "related_field_set",
                "related_field__another_related_field",
                "related_field__another_related_field__even_more_related_field",
            )
        )
```

--------------------------------

### Set action icon with @action(icon="person")

Source: https://unfoldadmin.com/docs/actions/introduction

Use the `icon` parameter on the `@action` decorator to display a custom icon for the action. The example defines a custom action that passes through the request and queryset.

```python
# admin.py

from django.db.models import QuerySet
from django.http import HttpRequest

from unfold.decorators import action


@action(description="Custom action", icon="person")
def custom_action(self, request: HttpRequest, queryset: QuerySet):
    pass

```

--------------------------------

### Render tabs in custom template with tab_list tag

Source: https://unfoldadmin.com/docs/tabs/dynamic

Template example that loads unfold tags and uses the tab_list tag with the unique page name to render tabs. Requires loading 'unfold' template tags first.

```html
{% extends "admin/base_site.html" %}

{% load unfold %}

{% block content %}
    {% tab_list "custom_page" %}
{% endblock %}

```

--------------------------------

### Default cohort component with component_class

Source: https://unfoldadmin.com/docs/components/cohort

Use this template code to render the cohort component with a custom component class. The component_class parameter refers to the class that prepares the data, as shown in the 'Custom cohort data preparation' example.

```html
{% load unfold %}

{% component "unfold/components/chart/cohort.html" with component_class="MyCohortComponent" %}
{% endcomponent %}

```

--------------------------------

### Action with permissions (method and built-in)

Source: https://unfoldadmin.com/docs/actions/introduction

Demonstrates defining an action with both a custom permission method (has_custom_action_permission) and a Django built-in permission ('auth.view_user'). The custom method receives the request and optionally the object instance.

```python
from django.contrib import admin
from django.contrib.auth.models import User

from unfold.admin import ModelAdmin
from unfold.decorators import action


@admin.register(User)
class UserAdmin(ModelAdmin):
    @action(
        description="Custom action",
        permissions=["custom_action", "auth.view_user"],  # Using both permission types
    )
    def custom_action(self, request, queryset):
        pass

    def has_custom_action_permission(self, request, obj=None):
        # Custom permission logic here
        return request.user.is_superuser

```

--------------------------------

### package.json scripts for Tailwind build and watch

Source: https://unfoldadmin.com/docs/styles-scripts/customizing-tailwind

Add these scripts to your package.json to automate the Tailwind compilation. The tailwind:watch script watches for changes, and tailwind:build performs a one-time build.

```json
{
  "scripts": {
    "tailwind:watch": "npx tailwindcss -i styles.css -o your_project/static/css/styles.css --minify --watch",
    "tailwind:build": "npx tailwindcss -i styles.css -o your_project/static/css/styles.css --minify"
  }
  // rest of configuration
}

```
Tokens:
Raw