Skip to content

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.

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" %}