Pagination for a User-Friendly Django App

You can improve the user experience of your Django web app significantly by spreading your content over multiple pages instead of serving all of it at once.
This practice is called pagination.
To implement pagination, you have to consider page count, items per page, and the order of pages.

But if you’re using Django for your web projects, you’re in luck!
Django has the pagination functionality built in.
With only a few configuration steps, you can provide paginated content to your users.

In this tutorial, you’ll learn how to:

Decide when to use Django’s paginator
Implement pagination in class-based views
Implement pagination in function-based views
Add pagination elements to templates
Browse pages directly with paginated URLs
Combine Django pagination with JavaScript calls

This tutorial is for intermediate Python programmers with basic Django experience.
Ideally, you’ve completed some introductory tutorials or created your own smaller Django projects.
To have the best experience with this tutorial, you should know what models, views, and templates are and how to create them.
If you need a refresher, then check out the tutorial on how to build a portfolio app with Django.

Pagination in the Wild

Before you try your hand at building your own pagination flows with Django, it’s worth looking around to spot pagination in action.
Pagination is so common on bigger websites that you’ve most likely experienced it in one form or another when browsing the Internet.

What Pagination Is

Pagination describes the practice of distributing your website’s content across multiple consecutive pages instead of serving it on a single page.
If you visit shopping sites, blogs, or archives, you’re likely to encounter paginated content.

On GitHub, you’ll find paginated content on Django’s pull requests page.
When you reach the bottom of the page, you can navigate to other pages:

Imagine how crowded the bottom of the page would be if all the page numbers were displayed.
What’s more, consider how long the page would take to load if all the issues were displayed at once instead of being spread over 615 pages.

You could even argue that having page numbers is unnecessary.
How could anybody know which issue is on which page?
For that reason, some sites ditch page numbers entirely and give you a condensed form of pagination.

The PyCoder’s Weekly Newsletter paginates its archive with Previous and Next buttons.
This type of pagination lets you conveniently browse through all newsletter issues:

Underneath the Subscribe button, you see the pagination controls for navigating to the previous and next issues.
Thanks to this pagination technique, you’re able hop from one newsletter issue to another instead of selecting issues from the archive one by one.

You can also see pagination in action when you’ve got more than one hundred objects in your Django admin interface.
To access more content, you have to click another page number:

Instead of showing a list of all 3,776 items, the Django admin divides the content into 38 pages.
Again, imagine how overwhelming the Django admin interface would be if all the content were presented in one giant table!

But pagination is not only used in the front-end design of websites.
It’s also very common to paginate the content of API responses.
The Random User API is one of many REST APIs that give you the option of paginating the response:

By adding a results=2 parameter, you tell the Random User API that you only want two results per response.
With the page parameter, you can navigate to a specific page of these paginated responses.

Once you know what pagination is, you’ll probably notice it often while surfing the Web.
In thinking about implementing pagination in your projects, it’s worth taking a closer look at when to use pagination and when not to use it.