Skip to main content

Django generic view breadcrumbs

Project description


Test Codacy Badge status Codacy Badge PyPI version

PyPI - Django Version PyPI - Python Version Downloads

All Contributors

Table of Contents


This package provides a set of breadcrumb mixin classes that can be added to any django class based view and requires adding just {% render_breadcrumbs %} to the base template.


In the base.html template add the render_breadcrumbs tag and any template that inherits the base should have breadcrumbs included.




{% load view_breadcrumbs %}

{% block breadcrumbs %}
    {% render_breadcrumbs %} {# Optionally provide a custom template e.g {% render_breadcrumbs "view_breadcrumbs/bootstrap5.html" %} #}
{% endblock %}

And your create.html.

{% extends "base.html" %}


$ pip install django-view-breadcrumbs

Add view_breadcrumbs to your INSTALLED_APPS


Breadcrumb mixin classes provided.

  • BaseBreadcrumbMixin - Subclasses requires a crumbs class property.
  • CreateBreadcrumbMixin - For create views Home / Posts / Add Post
  • DetailBreadcrumbMixin - For detail views Home / Posts / Post 1
  • ListBreadcrumbMixin - For list views Home / Posts
  • UpdateBreadcrumbMixin - For Update views Home / Posts / Post 1 / Update Post 1
  • DeleteBreadcrumbMixin - For Delete views this has a link to the list view to be used as the success URL.


NOTE :warning:

  • Make sure that "django.template.context_processors.request" is added to your TEMPLATE OPTIONS setting.
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.request", # <- This context processor is required

Modify the defaults using the following:

Name Default Description Options
BREADCRUMBS_TEMPLATE "view_breadcrumbs/bootstrap5.html" Template used to render breadcrumbs. Predefined Templates
BREADCRUMBS_HOME_LABEL Home Default label for the root path



Site wide
BREADCRUMBS_TEMPLATE = "my_app/breadcrumbs.html"
Overriding the breadcrumb template for a single view

Update the base.html

{% render_breadcrumbs "my_app/breadcrumbs.html" %}


Site wide
Overriding the Home label for a specific view
from django.utils.translation import gettext_lazy as _
from view_breadcrumbs import DetailBreadcrumbMixin
from django.views.generic import DetailView
from demo.models import TestModel

class TestDetailView(DetailBreadcrumbMixin, DetailView):
     model = TestModel
     home_label = _("My new home")
     template_name = "demo/test-detail.html"



Translation support




django-view-breadcrumbs includes generic mixins that can be added to a class based view.

Using the generic breadcrumb mixin each breadcrumb will be added to the view dynamically and can be overridden by providing a crumbs property.

View Configuration

NOTE: :warning:

  • Model based views should use a pattern view_name=model_verbose_name_{action}
Actions View Class View name Sample Breadcrumb Example
list ListView {model.verbose_name}_list Home / Posts Posts Example
create CreateView {model.verbose_name}_create Home / Posts / Add Post
detail DetailView {model.verbose_name}_detail Home / Posts / Test - Post
change UpdateView {model.verbose_name}_update Home / Posts / Test - Post / Update Test - Post
delete DeleteView {model.verbose_name}_delete N/A
N/A TemplateView N/A N/A See: Custom View
N/A FormView N/A N/A See: Custom View
N/A AboutView N/A N/A See: Custom View
N/A View N/A N/A See: Custom View


Actions View Class View name Sample Breadcrumb Example
N/A SingleTableMixin N/A N/A See: demo table view
N/A MultiTableMixin N/A N/A See: demo table view
N/A SingleTableView N/A N/A Same implementation as SingleTableMixin

For more examples see: demo app

URL Configuration

Based on the table of actions listed above there's a strict view_name requirement that needs to be adhered to in order for breadcrumbs to work.

This can be manually entered in your or you can optionally use the following class properties instead of hardcoding the view_name.

    path("tests/", TestListsView.as_view(), name=TestListsView.list_view_name),


Sample crumbs: Posts

In your

  urlpatterns = [
      path("posts/", views.PostList.as_view(), name="post_list"),
      # OR
      path("posts/", views.PostList.as_view(), name=views.PostList.list_view_name),

All crumbs use the home root path / as the base this can be excluded by specifying add_home = False

from django.views.generic import ListView
from view_breadcrumbs import ListBreadcrumbMixin

class PostList(ListBreadcrumbMixin, ListView):
    model = Post
    template_name = "app/post/list.html"
    add_home = False

Sample crumbs: Home / Posts / Test - Post

In your

  urlpatterns = [
      path("posts/<slug:slug>/", views.PostDetail.as_view(), name="post_detail"),
      # OR
      path("posts/<slug:slug>/", views.PostDetail.as_view(), name=views.PostDetail.detail_view_name),

from django.views.generic import DetailView
from view_breadcrumbs import DetailBreadcrumbMixin

class PostDetail(DetailBreadcrumbMixin, DetailView):
    model = Post
    template_name = "app/post/detail.html"
    breadcrumb_use_pk = False

Custom crumbs: Home / My Test Breadcrumb

URL configuration.

    urlpatterns = [
       path("my-custom-view/", views.CustomView.as_view(), name="custom_view"),

from django.urls import reverse
from django.views.generic import View
from view_breadcrumbs import BaseBreadcrumbMixin
from demo.models import TestModel

class CustomView(BaseBreadcrumbMixin, View):
    model = TestModel
    template_name = "app/test/custom.html"
    crumbs = [("My Test Breadcrumb", reverse("custom_view"))]  # OR reverse_lazy


from django.urls import reverse
from django.views.generic import View
from view_breadcrumbs import BaseBreadcrumbMixin
from demo.models import TestModel
from django.utils.functional import cached_property

class CustomView(BaseBreadcrumbMixin, View):
    template_name = "app/test/custom.html"

    def crumbs(self):
        return [("My Test Breadcrumb", reverse("custom_view"))]

Refer to the demo app for more examples.

Using multiple apps

To reference models from a different application you need to override the app_name class attribute.

Example: Using a Library model that is imported from a custom application that you want to render in a demo app view.



class LibraryDetailView(DetailBreadcrumbMixin, DetailView):
    model = Library
    app_name = "demo"

Running locally

$ git clone
$ make install-dev
$ make migrate
$ make run

Spins up a django server running the demo app.



To file a bug or submit a patch, please head over to django-view-breadcrumbs on github.

If you feel generous and want to show some extra appreciation:

Support me with a :star:

Buy me a coffee

Contributors ✨

Thanks goes to these wonderful people (emoji key):





This project follows the all-contributors specification. Contributions of any kind welcome!

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-view-breadcrumbs-2.5.1.tar.gz (47.7 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page