Crispy Forms¶
FormHelper is an object attached to a form that describes: - The attributes of the
<form>tag (method, action, id, class) - Rendering behavior - Layout — the structure and order of fields
FormHelper architecture¶
NoteForm
│
├── fields (Django standard)
│ ├── title CharField
│ ├── content TextField
│ └── ...
│
└── helper = FormHelper() ← crispy adds this
├── form_method = 'post' ← <form method="post">
├── form_id = 'note-form' ← <form id="note-form">
├── form_tag = True ← render <form>...</form>
└── layout = Layout(...) ← field structure
├── Fieldset(...) ← <fieldset><legend>
│ ├── Field('title') ← a single field with attrs
│ └── Row(...) ← <div class="row">
│ ├── Column(...) ← <div class="col-md-4">
│ └── Column(...) ← <div class="col-md-8">
├── Submit(...) ← <button type="submit">
└── HTML('<hr>') ← arbitrary HTML
Rendering pipeline¶
{% crispy form %}
│
▼
crispy_forms templatetag
│ Finds form.helper
│ Finds form.helper.layout
▼
Layout.render(form, context)
│
├── Fieldset.render()
│ ├── Field('title').render() → field.html template
│ └── Row.render()
│ └── Column.render()
├── Submit.render() → baseinput.html template
└── HTML.render() → direct string
│
▼
Bootstrap 5 HTML
(form-control, mb-3, row, col-md-4, invalid-feedback...)
Layout object attributes¶
# kwargs → HTML attributes
Field('title', placeholder='Підказка') # placeholder="Підказка"
Field('title', autofocus=True) # autofocus
Field('title', data_custom="val") # data-custom="val" (underscore → hyphen)
Field('title', css_class="extra") # extra CSS class
Field('title', type="hidden") # hidden input
# Wrapping div
Field('title', wrapper_class="mt-3") # class for <div class="mb-3 mt-3">
Where to use crispy vs. hand-written HTML — the rule¶
| Situation | Approach |
|---|---|
| The form takes up a whole page | {% crispy form %} — full control through Layout |
| Quick prototype | {{ form\|crispy }} — no FormHelper, just Bootstrap styles |
| A single field embedded in a page | {{ form.title\|as_crispy_field }} |
| A form without Bootstrap (API, email) | {{ form.as_p }} or form.cleaned_data directly |
Full NoteForm code with FormHelper and Layout¶
# hello_app/forms.py
from django import forms
from crispy_forms.helper import FormHelper
from crispy_forms.layout import (
Layout, Submit, Row, Column,
Fieldset, HTML, Div, Field
)
from .models import Note, Notebook, Tag
class NoteForm(forms.ModelForm):
class Meta:
model = Note
fields = ['title', 'content', 'priority', 'notebook', 'tags', 'is_pinned']
# ↑ NO widget attrs at all — crispy adds Bootstrap classes automatically!
def __init__(self, *args, user=None, **kwargs):
super().__init__(*args, **kwargs)
# Security: filter FKs by the current user
if user is not None:
self.fields['notebook'].queryset = Notebook.objects.filter(user=user)
self.fields['tags'].queryset = Tag.objects.filter(user=user)
self.fields['notebook'].empty_label = '— без записника —'
# FormHelper — describe the form in Python code
self.helper = FormHelper()
self.helper.form_method = 'post'
self.helper.form_id = 'note-form'
# Layout — field structure
self.helper.layout = Layout(
# Section 1: main information
Fieldset('Основна інформація',
Field('title', placeholder='Назва нотатки...', autofocus=True),
Row(
Column('priority', css_class='col-md-4'),
Column('notebook', css_class='col-md-8'),
),
),
# Section 2: content
Fieldset('Зміст нотатки',
Field('content', rows=8, placeholder='Текст нотатки...'),
),
# Section 3: tags and options
Fieldset('Теги та параметри',
'tags',
Div(Field('is_pinned'), css_class='form-check mt-2'),
),
# Divider
HTML('<hr class="my-4">'),
# Buttons
Submit('submit', 'Зберегти нотатку', css_class='btn btn-primary me-2'),
HTML('<a href="javascript:history.back()" class="btn btn-outline-secondary">Скасувати</a>'),
)
{% crispy form %} step by step¶
1. {% load crispy_forms_tags %} — registers the tag
2. {% crispy form %} — calls do_uni_form() in crispy_forms_tags.py
3. Finds form.helper — our FormHelper with its Layout
4. Renders form.helper.layout:
├── Fieldset('Основна інформація', ...) →
│ <fieldset>
│ <legend>Основна інформація</legend>
│ ...fields...
│ </fieldset>
│
├── Field('title', placeholder='...') →
│ <div class="mb-3">
│ <label for="id_title" class="form-label">Заголовок *</label>
│ <input type="text" name="title" id="id_title"
│ class="form-control" placeholder="Назва нотатки..."
│ autofocus>
│ </div>
│
├── Row(Column('priority', css_class='col-md-4'), ...) →
│ <div class="row">
│ <div class="col-md-4">...priority field...</div>
│ <div class="col-md-8">...notebook field...</div>
│ </div>
│
└── Submit('submit', 'Зберегти') →
<input type="submit" value="Зберегти" class="btn btn-primary me-2">
5. Adds <form method="post"> and {% csrf_token %} automatically
Template with {% crispy form %}¶
{% extends 'layouts/dashboard.html' %}
{% load crispy_forms_tags %}
{% block topbar_title %}{{ title }}{% endblock %}
{% block content %}
<div class="row">
<div class="col-lg-8">
<div class="card shadow-sm">
<div class="card-header bg-primary text-white">
<h6 class="mb-0"><i class="bi bi-journal-plus me-2"></i>{{ title }}</h6>
</div>
<div class="card-body">
{% crispy form %}
{# ↑ One tag instead of 80 lines of HTML.
FormHelper + Layout in forms.py describe ALL of the Bootstrap markup. #}
</div>
</div>
</div>
</div>
{% endblock %}
The form_tag = False pattern — embedded forms¶
Sometimes a form is part of a larger page rather than a page of its own. For example: a todo list + an inline form for adding a new task on the same page.
Problem: if the template already has <form action="/todo/5/items/add/"> and crispy also renders
a <form>, you end up with a nested <form> — invalid HTML; browsers ignore the inner <form>.
Solution: self.helper.form_tag = False — crispy renders only the fields and buttons,
but not the <form>...</form> wrapper. The template provides the form tag itself.
# forms.py — TodoItemForm: embedded inside a <form> that exists in the template
class TodoItemForm(forms.Form):
text = forms.CharField(max_length=500, label='Завдання')
due_date = forms.DateField(required=False, widget=forms.DateInput(attrs={'type': 'date'}))
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
self.helper = FormHelper()
self.helper.form_tag = False # ← do not render <form>...</form>
self.helper.form_show_labels = False # ← no labels (compact look)
self.helper.layout = Layout(
Row(
Column(Field('text', placeholder='Нове завдання...'), css_class='col-md-7'),
Column(Field('due_date'), css_class='col-md-3'),
Column(Submit('submit', '+ Додати', css_class='btn btn-primary w-100'),
css_class='col-md-2'),
),
)
<!-- todo_detail.html — the template provides the <form> tag, crispy only the fields -->
<form method="post" action="{% url 'hello_app:todo_item_add' list.pk %}">
{% csrf_token %}
{% crispy item_form %} ← renders a Row with fields and a button, but WITHOUT <form>
</form>
| Scenario | form_tag |
|---|---|
| The form takes up its own page (note_create, note_edit) | True (default) |
| The form is embedded in a page (inline add item) | False |
Layout Elements — reference¶
from crispy_forms.layout import *
# Basic elements:
Field('field_name') # Field with label and errors
Field('field_name', css_class='custom') # + custom class
Field('field_name', placeholder='...') # + HTML attribute
Field('field_name', rows=8) # Textarea rows
Field('field_name', type='hidden') # Hidden input
# Structural:
Row(Column('f1', css_class='col-6'), Column('f2', css_class='col-6'))
# → <div class="row"><div class="col-6">f1</div><div class="col-6">f2</div></div>
Fieldset('Заголовок', Field('f1'), Field('f2'))
# → <fieldset><legend>Заголовок</legend>f1 f2</fieldset>
Div(Field('f1'), css_class='custom-div')
# → <div class="custom-div">f1</div>
HTML('<hr><p>Довільний HTML</p>')
# Buttons:
Submit('submit', 'Зберегти')
# → <input type="submit" class="btn btn-primary" value="Зберегти">
Submit('submit', 'Зберегти', css_class='btn btn-success')
# → custom class
ButtonHolder(Submit('s', 'OK'), HTML('<a href="#">Cancel</a>'))
# → wrapper for buttons
Navigation¶
- Previous: Forms Evolution
- Next: Dashboard Architecture