How to create a custom filter in Django Admin/CMS

It is literally amazing that Django provides so many built-in filters. Imagine how much time the Django admin panel saves us. Moreover, its filtration functionality is outstanding.

For example, you only have to define the list_filter in your admin class and boom – you get fully functional filters like this:

Just focus on list_filter

But what if you want to add custom filters based on specific criteria? Does Django provide a way to do this?

Well, as our programming partner, YES. YES. YES, Django does allow us to create custom filters.

Example Use Case

Suppose you have a model like this:

Now, you want to create filters based on:

1. Room Range:

   • 1 room, 2 rooms, 3 rooms, 4 or more rooms.

2. Building Age:

   • Under Construction, Less than a year, 1 to 2 years, 3 to 4 years, 5 to 10 years, '11 to 15 years, 16 to 20 years, 21 to 25 years', 26 to 30 years, 30 years or more.

Most importantly, this involves specific ranges. The database stores these values as strings, but filtration needs to handle them as integers or floats.

Create a New File: filter_utils.py

To create a custom filter, Django provides the tools through django.contrib. Start by importing admin:

If you Ctrl + Click on the admin keyword, you will land in the admin module. Here, you’ll notice various types of filters Django offers.

Just focus on the filters section:

Now, I am gonna use SimpleListFilter so, if you again Ctrl + Click to explore this class on it you will get into the SimpleListFilter class and ListFilter

Now, If you explore these classes, you’ll find these methods and attributes:

Methods:

• has_output
• choices
• queryset
• expected_parameters
• value

Attributes:

• title
• template
• used_parameters
• parameter_name
• lookup_choices

we can use them in creating filters. I am not gonna cover all of them since I don't need all but if you wanna learn about them check this official documentation
https://docs.djangoproject.com/en/5.1/ref/contrib/admin/filters/

Now, let's do this

Room Range Filter

This is my RoomRangeFilter

Here,
title: This method returns a list of tuples where:

• The first element is the coded value for the URL query.
• The second element is the human-readable name for the filter option.

lookups: Returns a list of tuples. The first element in each tuple is the coded value for the option that will appear in the URL query. The second element is the human-readable name for the option that will appear in the right sidebar

queryset: Returns the filtered queryset based on the value provided in the query string and retrievable via`self.value()

When applied, this filter will look like this:

Building Age Filter

Another example is a BuildingAgeFilter

But here is a tricky part

• Exclude empty and null values in your filter logic when needed.
• Handle data type conversions (e.g., casting strings to integers) to ensure the filter works correctly

They all come from query set (self, request, queryset) function parameters.

If you wanna learn more about this check the official Django documentation.

Folder Structure

Conclusion

Django’s admin panel makes filtering super easy, but custom filters give you extra flexibility. Using SimpleListFilter, you can create filters that fit your needs perfectly. Just override methods like queryset and lookups, and you’re good to go.

---

Stay Connected - @syedamahamfahim 🐬