Crispy Tailwind

1.0.3 · active · verified Fri Apr 17

crispy-tailwind provides a Tailwind CSS template pack for Django Crispy Forms, allowing developers to easily render forms with Tailwind's utility-first classes. It is currently at version 1.0.3 and has a moderately active release cadence, with frequent bug-fix releases and major versions adding support for newer Django and Python versions.

Common errors

```
ImproperlyConfigured: 'tailwind' isn't an allowed template pack.
```
cause The `CRISPY_ALLOWED_TEMPLATE_PACKS` setting is missing or does not include 'tailwind', or `crispy_tailwind` is not in `INSTALLED_APPS`.

fix Add `CRISPY_ALLOWED_TEMPLATE_PACKS = "tailwind"` to `settings.py`. Also, ensure `crispy_tailwind` is included in `INSTALLED_APPS` (after `crispy_forms`).
```
TemplateDoesNotExist at /my-form/ crispy_forms/whole_uni_form.html
```
cause Django Crispy Forms is looking for its default template pack's files, indicating crispy-tailwind's templates are not being found or recognized.

fix Verify that both `crispy_forms` and `crispy_tailwind` are in your `INSTALLED_APPS` in `settings.py` (in that order), and that `CRISPY_TEMPLATE_PACK = "tailwind"` is correctly set.
```
Forms render without Tailwind styles (plain HTML).
```
cause This usually means the Tailwind CSS framework itself is not correctly integrated into your Django project, or the `CRISPY_TEMPLATE_PACK` is not correctly set to 'tailwind'.

fix Ensure `CRISPY_TEMPLATE_PACK = "tailwind"` is set in `settings.py`. Crucially, confirm that Tailwind CSS is properly built, included, and available in your frontend assets for your Django templates.
```
NameError: name 'FormHelper' is not defined
```
cause `FormHelper` class was used in a `forms.py` file without being imported.

fix Add `from crispy_forms.helper import FormHelper` to the top of your `forms.py` file where `FormHelper` is used.

Warnings

breaking Crispy-tailwind 1.0.0 introduced significant breaking changes, dropping support for older Django and Python versions and requiring an updated `django-crispy-forms`.
Fix: Upgrade your Django project to Django >=4.2 and Python >=3.8. Also, ensure `django-crispy-forms` is at least version 2.0.0. Review the release notes for `crispy-tailwind 1.0.0` for full details.
gotcha The `crispy_tailwind` application must be listed in `INSTALLED_APPS` *after* `crispy_forms` to ensure its templates correctly override the base ones.
Fix: Ensure `INSTALLED_APPS` in `settings.py` is configured as: `['crispy_forms', 'crispy_tailwind', ...]`. The order matters for template loading.
gotcha crispy-tailwind only provides the HTML structure with Tailwind CSS classes; it does not include or manage the Tailwind CSS framework itself. Your Django project must still be set up to compile and serve Tailwind CSS.
Fix: Refer to the official Tailwind CSS documentation and your Django project's setup guide to correctly integrate and build Tailwind CSS (e.g., via PostCSS, CDN, or Tailwind CLI) for your frontend.
gotcha Forgetting to set `CRISPY_TEMPLATE_PACK = "tailwind"` or setting `CRISPY_ALLOWED_TEMPLATE_PACKS` incorrectly will result in forms rendering with default (usually Bootstrap-like) styles or template errors.
Fix: In your `settings.py`, ensure you have both `CRISPY_ALLOWED_TEMPLATE_PACKS = "tailwind"` and `CRISPY_TEMPLATE_PACK = "tailwind"` defined.

Install

pip install crispy-tailwind Install crispy-tailwind

Imports

FormHelper
```
from crispy_forms.helper import FormHelper
```
Used in forms.py to customize form rendering.
Layout
```
from crispy_forms.layout import Layout, Submit
```
Used in forms.py to define custom form layouts.

Quickstart

After installing, add 'crispy_forms' and 'crispy_tailwind' to your `INSTALLED_APPS` in `settings.py`. Crucially, set `CRISPY_ALLOWED_TEMPLATE_PACKS = "tailwind"` and `CRISPY_TEMPLATE_PACK = "tailwind"`. Then, in your Django forms, instantiate a `FormHelper` and define your layout. Finally, render the form in your template using `{% load crispy_forms_tags %}` and `{% crispy form %}`.

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

CRISPY_ALLOWED_TEMPLATE_PACKS = "tailwind"
CRISPY_TEMPLATE_PACK = "tailwind"

# forms.py
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', 'Send', css_class='btn-primary mt-4')
        )

# template.html (e.g., in a Django view)
# {% load crispy_forms_tags %}
# <form method="post">
#     {% csrf_token %}
#     {% crispy form %}
# </form>

view raw JSON →