ModelAdmin List FiltersLink to this heading#ModelAdmin classes can define list filters that appear in the right sidebar\nof the change list page of the admin, as illustrated in the following\nscreenshot:
![\"/el/4.1/_images/list_filter.png\"](\"/el/4.1/_images/list_filter.png\")
\nTo activate per-field filtering, set ModelAdmin.list_filter to a list\nor tuple of elements, where each element is one of the following types:
A field name.
A subclass of django.contrib.admin.SimpleListFilter.
A 2-tuple containing a field name and a subclass of\ndjango.contrib.admin.FieldListFilter.
See the examples below for discussion of each of these options for defining\nlist_filter.
The simplest option is to specify the required field names from your model.
\nEach specified field should be either a BooleanField, CharField,\nDateField, DateTimeField, IntegerField, ForeignKey or\nManyToManyField, for example:
class PersonAdmin(admin.ModelAdmin):\n list_filter = ('is_staff', 'company')\nField names in list_filter can also span relations\nusing the __ lookup, for example:
class PersonAdmin(admin.UserAdmin):\n list_filter = ('company__name',)\nSimpleListFilterLink to this heading#For custom filtering, you can define your own list filter by subclassing\ndjango.contrib.admin.SimpleListFilter. You need to provide the title\nand parameter_name attributes, and override the lookups and\nqueryset methods, e.g.:
from datetime import date\n\nfrom django.contrib import admin\nfrom django.utils.translation import gettext_lazy as _\n\nclass DecadeBornListFilter(admin.SimpleListFilter):\n # Human-readable title which will be displayed in the\n # right admin sidebar just above the filter options.\n title = _('decade born')\n\n # Parameter for the filter that will be used in the URL query.\n parameter_name = 'decade'\n\n def lookups(self, request, model_admin):\n """\n Returns a list of tuples. The first element in each\n tuple is the coded value for the option that will\n appear in the URL query. The second element is the\n human-readable name for the option that will appear\n in the right sidebar.\n """\n return (\n ('80s', _('in the eighties')),\n ('90s', _('in the nineties')),\n )\n\n def queryset(self, request, queryset):\n """\n Returns the filtered queryset based on the value\n provided in the query string and retrievable via\n `self.value()`.\n """\n # Compare the requested value (either '80s' or '90s')\n # to decide how to filter the queryset.\n if self.value() == '80s':\n return queryset.filter(\n birthday__gte=date(1980, 1, 1),\n birthday__lte=date(1989, 12, 31),\n )\n if self.value() == '90s':\n return queryset.filter(\n birthday__gte=date(1990, 1, 1),\n birthday__lte=date(1999, 12, 31),\n )\n\nclass PersonAdmin(admin.ModelAdmin):\n list_filter = (DecadeBornListFilter,)\nFieldListFilterLink to this heading#Finally, if you wish to specify an explicit filter type to use with a field you\nmay provide a list_filter item as a 2-tuple, where the first element is a\nfield name and the second element is a class inheriting from\ndjango.contrib.admin.FieldListFilter, for example:
class PersonAdmin(admin.ModelAdmin):\n list_filter = (\n ('is_staff', admin.BooleanFieldListFilter),\n )\nHere the is_staff field will use the BooleanFieldListFilter. Specifying\nonly the field name, fields will automatically use the appropriate filter for\nmost cases, but this format allows you to control the filter used.
The following examples show available filter classes that you need to opt-in\nto use.
\nYou can limit the choices of a related model to the objects involved in\nthat relation using RelatedOnlyFieldListFilter:
class BookAdmin(admin.ModelAdmin):\n list_filter = (\n ('author', admin.RelatedOnlyFieldListFilter),\n )\nAssuming author is a ForeignKey to a User model, this will\nlimit the list_filter choices to the users who have written a book,\ninstead of listing all users.
You can filter empty values using EmptyFieldListFilter, which can\nfilter on both empty strings and nulls, depending on what the field\nallows to store:
class BookAdmin(admin.ModelAdmin):\n list_filter = (\n ('title', admin.EmptyFieldListFilter),\n )\nBy defining a filter using the __in lookup, it is possible to filter for\nany of a group of values. You need to override the expected_parameters\nmethod, and the specify the lookup_kwargs attribute with the appropriate\nfield name. By default, multiple values in the query string will be separated\nwith commas, but this can be customized via the list_separator attribute.\nThe following example shows such a filter using the vertical-pipe character as\nthe separator:
class FilterWithCustomSeparator(admin.FieldListFilter):\n # custom list separator that should be used to separate values.\n list_separator = '|'\n\n def __init__(self, field, request, params, model, model_admin, field_path):\n self.lookup_kwarg = '%s__in' % field_path\n super().__init__(field, request, params, model, model_admin, field_path)\n\n def expected_parameters(self):\n return [self.lookup_kwarg]\nList filters typically appear only if the filter has more than one choice. A\nfilter’s has_output() method controls whether or not it appears.
It is possible to specify a custom template for rendering a list filter:
\nclass FilterWithCustomTemplate(admin.SimpleListFilter):\n template = "custom_template.html"\nSee the default template provided by Django (admin/filter.html) for a\nconcrete example.