{"id":3976,"library":"django-widget-tweaks","title":"Django Widget Tweaks","description":"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.","status":"active","version":"1.5.1","language":"en","source_language":"en","source_url":"https://github.com/jazzband/django-widget-tweaks","tags":["Django","forms","templates","HTML attributes","CSS classes","frontend"],"install":[{"cmd":"pip install django-widget-tweaks","lang":"bash","label":"Install via pip"}],"dependencies":[{"reason":"Core functionality is based on Django forms.","package":"Django","optional":false},{"reason":"Requires Python 3.9 or newer.","package":"Python","optional":false}],"imports":[{"note":"Used as a template tag library in Django templates.","symbol":"widget_tweaks","correct":"{% load widget_tweaks %}"}],"quickstart":{"code":"import os\n\n# settings.py snippet\nINSTALLED_APPS = [\n    # ... other apps\n    'django.contrib.admin',\n    'django.contrib.auth',\n    'django.contrib.contenttypes',\n    'django.contrib.sessions',\n    'django.contrib.messages',\n    'django.contrib.staticfiles',\n    'widget_tweaks', # Add this line\n]\n\n# forms.py example\nfrom django import forms\n\nclass ContactForm(forms.Form):\n    name = forms.CharField(max_length=100, help_text='Your full name')\n    email = forms.EmailField(help_text='A valid email address')\n    message = forms.CharField(widget=forms.Textarea, help_text='Your message')\n\n# my_template.html example\n# {% load widget_tweaks %}\n#\n# <form method=\"post\">\n#     {% csrf_token %}\n#     <div class=\"form-group\">\n#         <label for=\"{{ form.name.id_for_label }}\">Name:</label>\n#         {% render_field form.name class=\"form-control\" placeholder=\"Your name\" %}\n#         {% if form.name.errors %}\n#             <div class=\"invalid-feedback d-block\">{% for error in form.name.errors %}{{ error }}{% endfor %}</div>\n#         {% endif %}\n#     </div>\n#     <div class=\"form-group\">\n#         <label for=\"{{ form.email.id_for_label }}\">Email:</label>\n#         {% render_field form.email type=\"email\" class=\"form-control\" %}\n#         {% if form.email.errors %}\n#             <div class=\"invalid-feedback d-block\">{% for error in form.email.errors %}{{ error }}{% endfor %}</div>\n#         {% endif %}\n#     </div>\n#     <div class=\"form-group\">\n#         <label for=\"{{ form.message.id_for_label }}\">Message:</label>\n#         {% render_field form.message class=\"form-control\" rows=\"5\" %}\n#         {% if form.message.errors %}\n#             <div class=\"invalid-feedback d-block\">{% for error in form.message.errors %}{{ error }}{% endfor %}</div>\n#         {% endif %}\n#     </div>\n#     <button type=\"submit\" class=\"btn btn-primary\">Submit</button>\n# </form>\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Django to 4.2+ or downgrade `django-widget-tweaks` to a version compatible with your Django installation.","message":"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.","severity":"breaking","affected_versions":"1.5.1 and newer"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that 'widget_tweaks' is present in your `INSTALLED_APPS` list in `settings.py`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}