crispy-bootstrap5

2026.3 · active · verified Sun Apr 12

crispy-bootstrap5 is a Bootstrap 5 template pack for the popular `django-crispy-forms` library. It enables Django forms to be rendered with Bootstrap 5 styles and components, including features like floating labels, accordions, and switches. The library follows a CalVer versioning scheme and releases frequently to keep pace with Django and Bootstrap updates.

Warnings

breaking Major versions frequently drop support for older Django and Python versions. Always check release notes before upgrading. For instance, version 2026.3 dropped support for Django 4.2, 5.0, 5.1 and Python 3.8, 3.9, while adding support for Django 6.0 and Python 3.14.
Fix: Consult the release notes for the version you are upgrading to and ensure your Django and Python environment matches the supported ranges. Upgrade Django/Python if necessary.
breaking Support for `django-crispy-forms` 2.2 and earlier was dropped in version 2024.10 of `crispy-bootstrap5`.
Fix: Ensure you are using `django-crispy-forms` version 2.3 or higher when upgrading to `crispy-bootstrap5` 2024.10 or newer.
gotcha For Django 5.2 and newer, templates were updated to include `aria-describedby` for `<fieldset>` elements and a parent `<div>` for errors, improving accessibility. Older versions might not be fully accessible or compatible with Django 5.2's expectations without these changes.
Fix: Upgrade to `crispy-bootstrap5` 2025.4 or newer to ensure full accessibility and compatibility with Django 5.2's updated form rendering.
gotcha When using `FormHelper` to define complex layouts in your form, you should use the `{% crispy form %}` template tag instead of the `{{ form|crispy }}` filter. The filter provides basic rendering, similar to `as_p`, `as_ul`, or `as_table`, and does not allow for layout customization defined in `FormHelper`.
Fix: If you are customizing your form layout using `FormHelper`, always use `{% crispy form %}` in your templates. Use `{{ form|crispy }}` for simple forms without custom layouts.
deprecated Pre-CalVer versions (0.x) used a different versioning scheme and may not receive updates or support. The project switched to CalVer (YYYY.Minor) with version 2023.10.
Fix: It is highly recommended to upgrade to a CalVer version (2023.10 or newer) to ensure you receive ongoing support and updates.

Install

pip install crispy-bootstrap5 django-crispy-forms Install with pip

Imports

FormHelper
```
from crispy_forms.helper import FormHelper
```
Used to programmatically define form rendering behavior.
Layout
```
from crispy_forms.layout import Layout
```
Base class for defining form layouts. Other layout objects like Row, Column, Submit are also commonly imported from crispy_forms.layout.
FloatingField
```
from crispy_bootstrap5.bootstrap5 import FloatingField
```
A layout object for Bootstrap 5's floating labels. Other Bootstrap 5 specific layout objects like BS5Accordion and Switch are also imported from this module.
render_crispy_form
```
from crispy_forms.utils import render_crispy_form
```
Used to render a crispy form within Python code, for example in a Django view to return an AJAX response. Remember to pass the CSRF token via context if needed.

Quickstart

After installation, add `crispy_forms` and `crispy_bootstrap5` to `INSTALLED_APPS` in your `settings.py`. Then, configure `CRISPY_ALLOWED_TEMPLATE_PACKS` and `CRISPY_TEMPLATE_PACK` to 'bootstrap5'. In your Django template, load `crispy_forms_tags` and render your form using either `{{ form|crispy }}` for basic styling or `{% crispy form %}` if you've defined a `FormHelper` in your form class for advanced layout control.

# settings.py
INSTALLED_APPS = [
    # ...
    'crispy_forms',
    'crispy_bootstrap5',
    # ...
]

CRISPY_ALLOWED_TEMPLATE_PACKS = "bootstrap5"
CRISPY_TEMPLATE_PACK = 'bootstrap5'

# forms.py (example form)
from django import forms
from crispy_forms.helper import FormHelper
from crispy_forms.layout import Layout, Submit

class ContactForm(forms.Form):
    name = forms.CharField(label='Your Name', max_length=100)
    email = forms.EmailField(label='Your Email')
    message = forms.CharField(label='Your Message', widget=forms.Textarea)

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.helper = FormHelper()
        self.helper.layout = Layout(
            'name',
            'email',
            'message',
            Submit('submit', 'Submit', css_class='btn btn-primary')
        )

# views.py (example view)
from django.shortcuts import render
from .forms import ContactForm

def contact_view(request):
    form = ContactForm()
    return render(request, 'contact.html', {'form': form})

# templates/contact.html
{% load crispy_forms_tags %}

<form method="post">
    {% csrf_token %}
    {% crispy form %}
</form>

view raw JSON →