Quick Start¶
Basic form¶
With FORM_RENDERER set, any Django form renders with DaisyUI styling:
# forms.py
from django import forms
class ContactForm(forms.Form):
name = forms.CharField()
email = forms.EmailField()
message = forms.CharField(widget=forms.Textarea)
<!-- template.html; the base template loads the CSS and the scripts -->
<form method="post" class="max-w-md mx-auto">
{% csrf_token %}
{{ form }}
<button type="submit" class="btn btn-primary mt-4">Send</button>
</form>
The installation guide shows the <head> with the scripts in the order they must load.
Each field renders inside a <fieldset class="fieldset"> with a label, help text and errors. A required field shows a red * after its label. Errors sit inline under a field that has help text and in a tooltip on a field without.
Per-form styling¶
If you don't want to set FORM_RENDERER globally, use the form base classes:
# forms.py
from django import forms
from django_formwork import FormworkForm, FormworkModelForm
from .models import Profile
class ContactForm(FormworkForm):
name = forms.CharField()
email = forms.EmailField()
class ProfileForm(FormworkModelForm):
class Meta:
model = Profile
fields = ["name", "bio", "avatar"]
Formwork widgets¶
The widget names follow Django's and shadow django.forms on purpose, so import the module and write widgets.Select:
from django import forms
from django_formwork import widgets
class ExampleForm(forms.Form):
# Toggle switch, with the label beside it
dark_mode = forms.BooleanField(widget=widgets.ToggleInput, required=False)
# Range slider
volume = forms.IntegerField(widget=widgets.Range(attrs={"min": 0, "max": 100}))
# Star rating
rating = forms.TypedChoiceField(
choices=widgets.Rating.make_choices(5),
coerce=int,
widget=widgets.Rating,
)
# Password with a show/hide button
password = forms.CharField(widget=widgets.PasswordInput)
# Dropdown; a search box appears past ten options
country = forms.ChoiceField(
choices=[("us", "United States"), ("de", "Germany")],
widget=widgets.Select,
)
# Multi-select dropdown with checkboxes
languages = forms.MultipleChoiceField(
choices=[("py", "Python"), ("js", "JavaScript")],
widget=widgets.SelectMultiple,
)
# Free text with suggestions
topic = forms.CharField(
widget=widgets.ComboBox(suggestions=["Python", "Django", "htmx"]),
)
# Number between - and + buttons
seats = forms.IntegerField(widget=widgets.StepperNumberInput(integer=True, min=1))
# Native date input
start = forms.DateField(widget=widgets.DateInput)
# Drag-and-drop file upload
attachment = forms.FileField(widget=widgets.FileDropzoneInput)
# Image upload with preview
avatar = forms.ImageField(widget=widgets.ImageDropzoneInput)
The widget reference lists every widget and its parameters.
Server-side textarea validation¶
ValidatedTextarea sends the textarea content to a server-side view as the user types, and highlights error spans in real time.
# views.py
import re
from django_formwork import FormworkValidateView
TYPOS = {"teh": "the", "recieve": "receive"}
class SpellCheckView(FormworkValidateView):
def get_errors(self, text: str, **kwargs) -> list[dict]:
return [
{
"message": f"Did you mean {TYPOS[word.group().lower()]!r}?",
"start": word.start(),
"end": word.end(),
}
for word in re.finditer(r"\w+", text)
if word.group().lower() in TYPOS
]
# urls.py
from django.urls import path
from .views import SpellCheckView
urlpatterns = [
path("validate/spell/", SpellCheckView.as_view(), name="spell-check"),
]
# forms.py
from django import forms
from django.urls import reverse_lazy
from django_formwork import widgets
class PostForm(forms.Form):
content = forms.CharField(
widget=widgets.ValidatedTextarea(validate_url=reverse_lazy("spell-check")),
)
The textarea sends its text only when it has an id. A form field gets one from the form's auto_id. A form with auto_id=False, or a widget rendered without attrs={"id": ...}, renders a textarea that never validates.
CSRF exemption
FormworkValidateView is CSRF-exempt because it only reads the posted text. Use it for read-only checks. A view that writes to the database or sends an email needs a regular Django view with CSRF protection.
Server-side search¶
Select, SelectMultiple, ComboBox and ComboBoxMultiple search on the server when the widget gets a search_queryset. Wire the URL pattern once:
# urls.py
from django.urls import include, path
urlpatterns = [
path("__formwork__/", include("django_formwork.urls")),
]
Then give the widget the rows to search, the fields to match and an access rule:
# forms.py
from django import forms
from django.contrib.auth.decorators import login_required
from django_formwork import FormworkForm, widgets
from .models import City
def cities(request):
return City.objects.filter(active=True)
class CityForm(FormworkForm):
city = forms.ModelChoiceField(
queryset=City.objects.filter(active=True),
widget=widgets.Select(
search_queryset=cities,
search_fields=["name", "country__name"],
search_decorator=login_required,
),
)
The form class registers the search when Python creates it. Formwork imports the forms module of each installed app at startup, so a search declared there works in every worker from the first request. search_queryset is a callable that takes the request; the endpoint calls it for each search, so it can scope the rows to the user. search_decorator is required: pass an auth decorator such as login_required, or None for a public endpoint. The views reference covers the endpoint, paging, ranked search and search templates.
Template tags¶
{% load formwork %}
<!-- JS module: core plus every widget component; load it after htmx and before Alpine -->
{% formwork_js %}
<!-- Section forms (opt-in); load it after htmx -->
{% formwork_sections_js %}
<!-- Hidden input that names the section a section form saves -->
{% formwork_section "general" %}