django-admin-superfilter

Advanced, modern filtering for Django admin changelists, with saved filters and selectable columns.

Features

• Search-bar style filter UI injected into Django admin changelists
• Type-aware filtering for text, numeric, boolean, choice, date, datetime and relation fields
• Field path traversal such as author__email
• Saved filters per authenticated user
• Column selection and ordering persisted with saved filters
• AJAX-backed relation picker using Django admin Select2 assets
• Support for custom filter fields via SuperFilterField
• Single JSON query parameter for rules (sf) and one for visible columns (sfc)
• Works without templates overrides

Requirements

• Python 3.10+
• Django 4.0+

Installation

Install the package:

pip install django-admin-superfilter

Add the app to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    "superfilter",
]

Run migrations:

python manage.py migrate

Quick start

from django.contrib import admin
from superfilter.admin import SuperFilterAdminMixin

from .models import Bird


@admin.register(Bird)
class BirdAdmin(SuperFilterAdminMixin, admin.ModelAdmin):
    list_display = ("species", "location", "count")
    search_fields = ("species",)

Important:

• Put SuperFilterAdminMixin before admin.ModelAdmin in the MRO.
• By default, filterable fields come from list_display.
• Non-model entries in list_display are ignored.
• Traversed model fields like location__city__name are supported.

What appears in the UI

The package adds a search-bar-like control above the changelist with:

• an add-filter button
• an inline text input with suggestions for quick contains filters
• filter badges for current rules
• an Apply button
• an Auto apply checkbox (enabled by default)
• a split menu with Save
• a Reset button
• a Columns toggle button
• a collapsible column chooser
• saved filter chips

Saved filters store both:

• the active filter rules
• the selected column list and order

Supported field kinds and operators

All fields

• set
• not_set

Text-like fields

Text-like fields include CharField, TextField, EmailField, SlugField, URLField, UUIDField.

Operators:

• set
• not_set
• eq
• neq
• contains
• not_contains
• in
• not_in

Numeric fields

Operators:

• set
• not_set
• eq
• neq
• gt
• lt
• gte
• lte

Boolean fields

Operators:

• set
• not_set
• true
• false

Choice fields

Operators:

• set
• not_set
• in
• not_in

Foreign key / relation fields

Operators:

• set
• not_set
• in
• not_in

Date and datetime fields

Operators:

• set
• not_set
• eq
• before
• after
• between

Semantics

• set means the field is considered populated
• not_set means the field is empty
• For text fields, empty means NULL or empty string
• For boolean fields, set / not_set only target NULL vs non-NULL
• contains uses icontains
• not_contains negates icontains
• between on date/datetime expects exactly two values
• Relation filters use selected related object primary keys

Configuration

SuperFilterAdminMixin exposes a few attributes:

• superfilter_param_name = "sf"
• superfilter_columns_param_name = "sfc"
• superfilter_fields = None
• superfilter_inline_filter_fields = None
• superfilter_page_size = 25
• superfilter_all_limit = 2000

Global Django settings for XLSX export throttling/paging:

• SUPERFILTER_MAX_EXPORT_LINES = 5000
• SUPERFILTER_MAX_PARALLEL_EXPORTS_PER_NODE = 5
• SUPERFILTER_MAX_EXPORT_LOCK_TIMEOUT = 1800 (seconds)

When export is enabled, the download dialog proposes paged ranges (1..N, N+1..2N, etc.). It also shows Nombre total de resultats: XXX, retrieved from an HTTP HEAD preflight on the same export URL using the current (including unapplied) filter state. The last range is trimmed to the remaining rows only. Before each download, the frontend sends the same HEAD preflight to check server capacity on the current hostname. For deployments that rewrite HEAD to GET, the preflight also sends dryrun=1 so the backend keeps preflight behavior. If all slots are used, it waits and polls until a slot is available (or the user cancels/closes the dialog).

Example:

class BirdAdmin(SuperFilterAdminMixin, admin.ModelAdmin):
    list_display = ("species", "location", "count")
    superfilter_inline_filter_fields = ("species", "location__city")
    superfilter_page_size = 50
    superfilter_all_limit = 5000

superfilter_inline_filter_fields controls the fields suggested by the inline input and their order. If omitted, all fields that support the contains operator are suggested. If a configured path is invalid or does not support contains, it is skipped and a warning is logged.

Restricting filterable fields

By default, filterable fields are taken from list_display.

To expose a different set of fields, use superfilter_fields:

class BirdAdmin(SuperFilterAdminMixin, admin.ModelAdmin):
    list_display = ("species", "location", "count")
    superfilter_fields = ("species", "count", "location__city")

This only affects filterable fields. Column selection still uses list_display.

Custom filter fields

You can plug in custom fields that do not map directly to a Django model field.

Create a subclass of SuperFilterField:

from django.db.models import Q
from superfilter.logic import SuperFilterField


class HasLargeCountField(SuperFilterField):
    path = "has_large_count"
    label = "Large count"
    kind = "choice"
    choices = [
        {"value": "yes", "label": "Yes"},
        {"value": "no", "label": "No"},
    ]

    def apply_rule(self, queryset, rule):
        values = set(rule.get("value") or [])
        if "yes" in values and "no" not in values:
            return queryset.filter(count__gte=100)
        if "no" in values and "yes" not in values:
            return queryset.filter(count__lt=100)
        return queryset

Register it in superfilter_fields:

class BirdAdmin(SuperFilterAdminMixin, admin.ModelAdmin):
    list_display = ("species", "location", "count")
    superfilter_fields = ("species", HasLargeCountField)

Saved filters

Saved filters are stored in the SavedSuperFilter model and are scoped by:

• user
• app label
• model name
• saved filter name

Notes:

• saving requires an authenticated user
• saved filters are private to the user

URL format

Rules are sent in the sf query parameter as JSON:

[
  {"field": "species", "op": "contains", "value": "owl"},
  {"field": "location", "op": "in", "value": [1, 2]},
  {"field": "count", "op": "gte", "value": 10}
]

Columns are sent in the sfc query parameter as JSON:

["location", "species", "count"]

Relation option loading

For relation filters, the package exposes an admin endpoint that:

• reuses the related admin's get_search_results() when available
• otherwise falls back to searching up to three text fields
• otherwise falls back to PK search for numeric terms

Static assets

The mixin injects:

• admin/css/vendor/select2/select2.min.css
• admin/js/vendor/select2/select2.full.min.js
• superfilter/superfilter.css
• superfilter/superfilter.js

No custom template override is required.

Limitations

• Filtering ignores callable/computed list_display entries unless implemented as SuperFilterField
• Column selection only works on entries present in list_display
• The package ships with admin-focused frontend assets and is not intended for non-admin pages

Example project

A runnable sample project is available in:

• examples/sampleapp/

Run it with:

cd examples/sampleapp
python manage.py migrate
python manage.py runserver

Development

Run tests from the repository root:

python manage.py test superfilter

Or use the sample project:

cd examples/sampleapp
python manage.py test

License

MIT. See LICENCE.md.