Skip to main content

Introduction

Django Unfold provides a comprehensive filtering system that extends Django’s built-in admin filters with modern, interactive UI components. The filters are designed to improve the user experience when working with large datasets in the admin interface.
All filters are located in unfold.contrib.filters.admin and extend Django’s native filter classes while adding enhanced functionality and styling.

Available Filter Types

Unfold offers seven categories of filters, each optimized for specific data types and use cases:

Dropdown Filters

Single and multiple selection dropdowns for choices and related fields

Autocomplete Filters

Search-enabled filters for large datasets with AJAX-powered autocomplete

Numeric Filters

Range, slider, and single value filters for numeric fields

Date/Time Filters

Date and datetime range pickers with intuitive calendar UI

Text Filters

Text search filters with case-insensitive matching

Checkbox & Radio

Multiple and single selection filters using checkboxes and radio buttons

Installation

Before using filters, add the filters app to your Django settings:
settings.py
INSTALLED_APPS = [
    # ... other apps
    "unfold",
    "unfold.contrib.filters",  # Enable filters
    "django.contrib.admin",
    # ...
]

Basic Usage

Filters are used in the list_filter attribute of your ModelAdmin classes. Here’s a basic example:
admin.py
from django.contrib import admin
from unfold.admin import ModelAdmin
from unfold.contrib.filters.admin import (
    DropdownFilter,
    RangeDateFilter,
    SingleNumericFilter,
)

from .models import Product


class CategoryFilter(DropdownFilter):
    title = "Category"
    parameter_name = "category"

    def lookups(self, request, model_admin):
        return (
            ("electronics", "Electronics"),
            ("clothing", "Clothing"),
            ("books", "Books"),
        )

    def queryset(self, request, queryset):
        if self.value():
            return queryset.filter(category=self.value())
        return queryset


@admin.register(Product)
class ProductAdmin(ModelAdmin):
    list_filter = [
        CategoryFilter,
        ("price", SingleNumericFilter),
        ("created_at", RangeDateFilter),
    ]

Filter Features

Faceted Counts

When Django’s show_facets is enabled, filters automatically display the count of items for each option.
admin.py
@admin.register(Product)
class ProductAdmin(ModelAdmin):
    show_facets = admin.ShowFacets.ALWAYS
    list_filter = [
        ("category", DropdownFilter),
    ]
This will display counts like “Electronics (42)” next to each filter option.

Custom Templates

Each filter type uses a specific template that can be overridden:
  • Field filters: unfold/filters/filters_field.html
  • Numeric range: unfold/filters/filters_numeric_range.html
  • Numeric slider: unfold/filters/filters_numeric_slider.html
  • Numeric single: unfold/filters/filters_numeric_single.html
  • Date range: unfold/filters/filters_date_range.html
  • Datetime range: unfold/filters/filters_datetime_range.html

Form Classes

Filters use dedicated form classes for rendering:
  • DropdownForm - Standard dropdown select
  • AutocompleteDropdownForm - AJAX-enabled autocomplete
  • CheckboxForm - Multiple checkboxes
  • RadioForm / HorizontalRadioForm - Radio buttons
  • SearchForm - Text input with search
  • SingleNumericForm - Single number input
  • RangeNumericForm - From/to number inputs
  • SliderNumericForm - Interactive range slider
  • RangeDateForm - Date range picker
  • RangeDateTimeForm - Datetime range picker

Migration from Django Filters

Unfold filters are designed as drop-in replacements for Django’s built-in filters:
Django FilterUnfold Replacement
SimpleListFilterDropdownFilter, RadioFilter, or CheckboxFilter
ChoicesFieldListFilterChoicesDropdownFilter or ChoicesRadioFilter
RelatedFieldListFilterRelatedDropdownFilter or RelatedCheckboxFilter
BooleanFieldListFilterBooleanRadioFilter
AllValuesFieldListFilterAllValuesCheckboxFilter
Simply import from unfold.contrib.filters.admin instead of django.contrib.admin.

Performance Considerations

For large datasets (>10,000 records), consider using AutocompleteSelectFilter instead of dropdown filters to avoid loading all options at once.

Next Steps

Explore each filter type in detail:
1

Dropdown Filters

Learn about single and multiple selection dropdowns View Dropdown Filters →
2

Autocomplete Filters

Implement search-enabled filters for large datasets View Autocomplete Filters →
3

Specialized Filters

Explore numeric, date/time, text, and choice filters View All Filter Types →

Build docs developers (and LLMs) love