Django Crispy Forms

2.6 · active · verified Fri Apr 10

Django Crispy Forms is a powerful third-party Django application that allows you to easily control the rendering behavior of your Django forms in a DRY (Don't Repeat Yourself) and elegant way. It provides tools to add CSS classes, customize layouts, and enhance form rendering with minimal effort. The current version is 2.6, and it maintains an active release cadence with several updates per year to support new Django and Python versions.

Warnings

breaking Version 2.0 removed all built-in Bootstrap template packs. These are now standalone packages (e.g., `crispy-bootstrap5`).
Fix: Install the appropriate template pack (e.g., `pip install crispy-bootstrap5`) and add it to `INSTALLED_APPS` and set `CRISPY_TEMPLATE_PACK` in your `settings.py`.
breaking Version 2.6 dropped support for Django 4.2, 5.0, and 5.1.
Fix: Upgrade your Django version to a supported one (e.g., Django 5.2 or later as per 2.4 release, or 6.0 as per 2.5 release) or downgrade `django-crispy-forms` to a compatible version.
breaking Version 2.5 dropped support for Python 3.8. Version 2.1 dropped support for Python 3.7.
Fix: Ensure your project uses Python 3.9 or newer for `django-crispy-forms` 2.5+, and Python 3.8 or newer for `django-crispy-forms` 2.1-2.4. Python 3.10 is the minimum requirement for 2.6.
gotcha Crispy Forms does not include static files (CSS/JS) for template packs. You must include them yourself.
Fix: Manually link the CSS and JavaScript files for your chosen CSS framework (e.g., Bootstrap) in your base templates. Refer to your CSS framework's documentation for correct setup.
gotcha Form validation errors may not appear if you are using complex layout objects or specific template customizations.
Fix: Ensure that `{{ form.errors }}` or `{{ form|as_crispy_errors }}` is included in your template to display non-field errors. For field-specific errors, ensure your layout objects are correctly structured to allow their display.
gotcha Not setting `CRISPY_TEMPLATE_PACK` globally may lead to forms not rendering 'crispy' by default, or with an unexpected template pack.
Fix: Add `CRISPY_TEMPLATE_PACK = 'your_template_pack'` (e.g., `'bootstrap5'`) to your `settings.py` to define the default template pack. You can also specify it per form or even per `{% crispy %}` tag.

Install

pip install django-crispy-forms Install core library
pip install crispy-bootstrap5 Install a template pack (e.g., Bootstrap 5)

Imports

FormHelper
```
from crispy_forms.helper import FormHelper
```
Used to programmatically define form rendering behavior.
Layout
```
from crispy_forms.layout import Layout
```
Primary class for defining custom form layouts.
Submit
```
from crispy_forms.layout import Submit
```
Layout object to add a submit button to your form.
Div
```
from crispy_forms.layout import Div
```
Layout object to group fields within a <div> tag.
Row
```
from crispy_forms.layout import Row
```
Layout object to create a Bootstrap row for multi-column layouts.
Fieldset
```
from crispy_forms.layout import Fieldset
```
Layout object to group fields within a <fieldset> tag.

Quickstart

This quickstart demonstrates how to define a Django form with `FormHelper` and `Layout` objects to customize its appearance using `django-crispy-forms`. It includes setting up a two-column row and a submit button. Remember to add `crispy_forms` and your chosen template pack (e.g., `crispy_bootstrap5`) to `INSTALLED_APPS` and configure `CRISPY_TEMPLATE_PACK` in your `settings.py`. In your template, load `crispy_forms_tags` and render the form using `{% crispy form %}`.

import os
from django import forms
from crispy_forms.helper import FormHelper
from crispy_forms.layout import Layout, Submit, Row, Column

# settings.py (excerpt)
# INSTALLED_APPS = [
#     ...,
#     'crispy_forms',
#     'crispy_bootstrap5', # Or your chosen template pack
# ]
# CRISPY_ALLOWED_TEMPLATE_PACKS = ['bootstrap5']
# CRISPY_TEMPLATE_PACK = 'bootstrap5'

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(
            Row(
                Column('name', css_class='form-group col-md-6 mb-0'),
                Column('email', css_class='form-group col-md-6 mb-0'),
                css_class='form-row'
            ),
            'message',
            Submit('submit', 'Send Message', css_class='btn btn-primary')
        )

# views.py (excerpt)
# from django.shortcuts import render
# def contact_view(request):
#     form = ContactForm()
#     return render(request, 'contact.html', {'form': form})

# contact.html (excerpt)
# {% load crispy_forms_tags %}
# <form method="post">
#     {% csrf_token %}
#     {% crispy form %}
# </form>

# To make this runnable in a minimal context (not a full Django app)
# This part is for demonstration only and assumes Django is configured
# and settings above are set if running in a real project.
if __name__ == '__main__':
    # This part is purely illustrative as it requires a full Django setup
    # and request cycle to actually render.
    # In a real Django app, you would define this in forms.py
    # and then render in a template using `{% crispy form %}`
    form_instance = ContactForm()
    print("Quickstart Form Helper and Layout defined successfully.")
    print("Remember to configure settings.py and your templates as per comments.")

view raw JSON →