django-widget-tweaks

django-widget-tweaks lets you adjust the rendering of Django form fields directly in your templates rather than in Python-level form or widget definitions. Through a small set of template tags and filters, you can add or replace CSS classes, set HTML attributes, and control widget markup at the point of rendering.

This keeps presentation concerns with designers and templates, so front-end tweaks like adding a Bootstrap class or a placeholder no longer require editing form classes. It is a long-standing Jazzband-maintained package widely used to bridge Django forms and modern CSS frameworks.

What You Get

• The render_field template tag for setting attributes with a clean HTML-like syntax
• Filters such as add_class, remove_class, set_attr, append_attr, and attr for granular tweaks
• The ability to style form fields for CSS frameworks without editing Python forms
• Compatibility with standard Django forms and widgets across supported Django versions

Common Use Cases

• Adding Bootstrap or Tailwind classes to Django form fields in templates
• Setting placeholder, autofocus, or data-* attributes on specific fields
• Letting front-end developers restyle forms without changing Python code

Under The Hood

Architecture - The package is a small Django app whose core lives in widget_tweaks/templatetags/widget_tweaks.py. It registers a render_field block tag and a set of filters (add_class, remove_class, set_attr, append_attr, attr) that operate on a form BoundField, cloning the field’s widget and mutating its attrs dict before rendering. Because it works on the bound field at template-render time, it never modifies the underlying Python form definition.

Tech Stack - Pure Python (100%), packaged as a standard Django reusable app added to INSTALLED_APPS. It depends only on Django itself and targets multiple Django and Python versions, verified through GitHub Actions CI.

Code Quality - The codebase is compact and well-tested, with a test suite and Codecov coverage reporting under the Jazzband umbrella. Maintenance is infrequent but the project is mature and stable, and the small surface area keeps regression risk low.

API Design - The API is intentionally template-first: {% render_field form.name class=“input” placeholder=”…” %} reads like HTML, and the filters compose naturally in Django template pipelines. This gives designers a shallow learning curve and keeps styling logic out of Python entirely.