ListView for displaying collections in Django

Introduction

ListView helps you show a list of items from your database easily. It saves time by handling common tasks like fetching and displaying data.

You want to show a list of blog posts on a page.

You need to display all users registered on your site.

You want to show a catalog of products in an online store.

You want to list comments under an article.

You want to paginate a long list of items automatically.

Syntax

Django

from django.views.generic import ListView
from .models import YourModel

class YourModelListView(ListView):
    model = YourModel
    template_name = 'yourapp/yourmodel_list.html'  # optional
    context_object_name = 'items'  # optional
    paginate_by = 10  # optional

model tells ListView which data to show.

template_name sets the HTML file to render. If not set, Django uses a default name.

Examples

Basic ListView showing all Book objects using default template and context name.

Django

class BookListView(ListView):
    model = Book

Custom template and context name for better clarity in the template.

Django

class AuthorListView(ListView):
    model = Author
    template_name = 'authors/list.html'
    context_object_name = 'authors_list'

Shows 5 products per page with automatic pagination controls.

Django

class ProductListView(ListView):
    model = Product
    paginate_by = 5

Sample Program

This example shows a simple Item model and a ListView that displays all items with pagination of 3 items per page. The template loops over items and shows their name and description. Pagination links let users move between pages.

Django

from django.db import models
from django.urls import path
from django.views.generic import ListView

# Model definition
class Item(models.Model):
    name = models.CharField(max_length=100)
    description = models.TextField()

    def __str__(self):
        return self.name

# ListView to display all items
class ItemListView(ListView):
    model = Item
    template_name = 'items/item_list.html'
    context_object_name = 'items'
    paginate_by = 3

# URL configuration
urlpatterns = [
    path('items/', ItemListView.as_view(), name='item-list'),
]

# Template (items/item_list.html) content:
# {% extends 'base.html' %}
# {% block content %}
# <h1>Items List</h1>
# <ul>
# {% for item in items %}
#   <li><strong>{{ item.name }}</strong>: {{ item.description }}</li>
# {% empty %}
#   <li>No items found.</li>
# {% endfor %}
# </ul>
# 
# {% if is_paginated %}
#   <div>
#     {% if page_obj.has_previous %}
#       <a href="?page={{ page_obj.previous_page_number }}">Previous</a>
#     {% endif %}
#     <span>Page {{ page_obj.number }} of {{ page_obj.paginator.num_pages }}</span>
#     {% if page_obj.has_next %}
#       <a href="?page={{ page_obj.next_page_number }}">Next</a>
#     {% endif %}
#   </div>
# {% endif %}
# {% endblock %}

Important Notes

ListView automatically fetches all objects of the model unless you override the query.

Pagination helps when you have many items to avoid long pages.

Common mistake: forgetting to create the template or using wrong context name causes errors.

Summary

ListView shows lists of database items easily with little code.

You can customize template, context name, and pagination.

It saves time and keeps your code clean and simple.