Django Widget Tweaks

1.5.1 · active · verified Sat Apr 11

Django Widget Tweaks is a Python library that allows developers to customize the rendering of Django form fields directly within templates using template tags and filters, rather than modifying Python-level form definitions. This enables front-end developers to easily add CSS classes and HTML attributes. It is actively maintained by Jazzband, with version 1.5.1 supporting Django 5.0 and released annually or more frequently.

Warnings

breaking Django Compatibility: Version 1.5.1 officially adds support for Django 5.0 and concurrently drops support for Django 4.1. Users on older Django versions (pre-4.2) should consult the `django-widget-tweaks` changelog to find a compatible version of the library.
Fix: Upgrade Django to 4.2+ or downgrade `django-widget-tweaks` to a version compatible with your Django installation.
gotcha Jinja2 Template Engine Incompatibility: `django-widget-tweaks` is built for Django's default template language (DTL). It does not natively integrate with Jinja2 template environments. Attempting to use `{% load widget_tweaks %}` directly in Jinja2 templates will fail.
Fix: For Jinja2, you must manually import and expose the desired functions (e.g., `render_field`, `add_class`) from `widget_tweaks.templatetags.widget_tweaks` into your Jinja2 environment's globals or filters. This requires custom setup in your Django project's Jinja2 configuration.
gotcha INSTALLED_APPS Requirement: The `django-widget-tweaks` template tags will not be available in your templates unless 'widget_tweaks' is explicitly added to the `INSTALLED_APPS` list in your project's `settings.py` file. This is a common oversight during initial setup.
Fix: Ensure that 'widget_tweaks' is present in your `INSTALLED_APPS` list in `settings.py`.
gotcha Purpose Misunderstanding: This library is strictly for *template-level* manipulation of HTML attributes and CSS classes on form fields. It is not intended to modify form field definitions or widgets in Python code (e.g., in `forms.py` or `models.py`).
Fix: If you need to define widget attributes or classes at the Python level (e.g., dynamically based on backend logic), use Django's built-in `widget.attrs` or form field initialization. `django-widget-tweaks` complements, but does not replace, Python-level form customization.

Install

pip install django-widget-tweaks Install via pip

Imports

widget_tweaks
```
{% load widget_tweaks %}
```
Used as a template tag library in Django templates.

Quickstart

After installing, add 'widget_tweaks' to your Django project's `INSTALLED_APPS` in `settings.py`. Then, in your Django templates, load the `widget_tweaks` library using `{% load widget_tweaks %}`. You can then use the `render_field` tag or various filters (like `add_class`) to customize form fields, adding HTML attributes and CSS classes directly in the template. This example demonstrates using `render_field` to apply Bootstrap classes and attributes.

import os

# settings.py snippet
INSTALLED_APPS = [
    # ... other apps
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'widget_tweaks', # Add this line
]

# forms.py example
from django import forms

class ContactForm(forms.Form):
    name = forms.CharField(max_length=100, help_text='Your full name')
    email = forms.EmailField(help_text='A valid email address')
    message = forms.CharField(widget=forms.Textarea, help_text='Your message')

# my_template.html example
# {% load widget_tweaks %}
#
# <form method="post">
#     {% csrf_token %}
#     <div class="form-group">
#         <label for="{{ form.name.id_for_label }}">Name:</label>
#         {% render_field form.name class="form-control" placeholder="Your name" %}
#         {% if form.name.errors %}
#             <div class="invalid-feedback d-block">{% for error in form.name.errors %}{{ error }}{% endfor %}</div>
#         {% endif %}
#     </div>
#     <div class="form-group">
#         <label for="{{ form.email.id_for_label }}">Email:</label>
#         {% render_field form.email type="email" class="form-control" %}
#         {% if form.email.errors %}
#             <div class="invalid-feedback d-block">{% for error in form.email.errors %}{{ error }}{% endfor %}</div>
#         {% endif %}
#     </div>
#     <div class="form-group">
#         <label for="{{ form.message.id_for_label }}">Message:</label>
#         {% render_field form.message class="form-control" rows="5" %}
#         {% if form.message.errors %}
#             <div class="invalid-feedback d-block">{% for error in form.message.errors %}{{ error }}{% endfor %}</div>
#         {% endif %}
#     </div>
#     <button type="submit" class="btn btn-primary">Submit</button>
# </form>

view raw JSON →