📝 Django Forms System

Why the Form System Exists

You could read submitted data straight out of request.POST, coerce every value by hand, check each one, and glue error messages back into the HTML yourself. People did exactly that for years, and it was a reliable source of bugs and security holes. Django's form layer exists so you never have to.

A Django form is a single Python class that owns four jobs at once:

• Render — produce the HTML inputs, labels, and help text.
• Validate — check every field against its rules and collect errors.
• Convert — turn raw strings from the browser into proper Python types (a real datetime.date, a Decimal, a bool).
• Redisplay — when validation fails, show the form again with the user's input intact and errors attached to the right fields.

💡 Analogy — the restaurant order pad. A waiter (the form) presents a menu (the fields), takes an order, and checks it makes sense (validation) before the ticket ever reaches the kitchen (your view logic). Without that check, customers order dishes that don't exist and specify impossible quantities — chaos behind the pass. The form is the disciplined intake step that keeps the kitchen sane.

The Form Lifecycle

The single most important idea in this whole lesson is the difference between an unbound and a bound form, and the pipeline that runs between them.

• An unbound form — ContactForm() — has no data attached. You render it for a fresh GET request.
• A bound form — ContactForm(request.POST) — has submitted data attached. Only bound forms can be validated.

When you call form.is_valid(), Django runs each field's conversion and validation, then the form-wide clean(). On success it populates the cleaned_data dictionary with typed values; on failure it fills form.errors instead.

Form vs. ModelForm

Django gives you two starting points, and picking the right one saves you a lot of typing.

forms.Form — the general-purpose form

Use it when the input does not map one-to-one to a database table: a contact form that sends an email, a search box, a "filter results" panel. You declare every field yourself.

# forms.py
from django import forms


class ContactForm(forms.Form):
    name = forms.CharField(max_length=100)
    email = forms.EmailField()
    message = forms.CharField(widget=forms.Textarea)
    subscribe = forms.BooleanField(required=False)

forms.ModelForm — the model-backed form

Use it when the form's whole purpose is to create or edit rows of one model — the everyday CRUD case. A ModelForm reads your model and builds matching fields, widgets, and validation automatically, and it can .save() straight to the database.

# forms.py
from django import forms
from .models import Article


class ArticleForm(forms.ModelForm):
    class Meta:
        model = Article
        fields = ["title", "content", "category", "tags"]
        # Prefer an explicit list over fields = "__all__" so a new
        # model field is never silently exposed on your public form.

Fields & Widgets

There is a distinction worth internalizing early: a field owns the data — its type, its validation, whether it's required. A widget owns the HTML — which input tag renders and what attributes it carries. One field can wear many widgets.

Common fields

Customizing widgets

Pass a widget instance with attrs to control the HTML — placeholders, sizes, CSS classes, and numeric bounds all live here.

# forms.py
from django import forms


class FeedbackForm(forms.Form):
    rating = forms.IntegerField(
        widget=forms.NumberInput(attrs={"min": 1, "max": 5}),
    )
    comments = forms.CharField(
        widget=forms.Textarea(attrs={"rows": 5, "placeholder": "Tell us more…"}),
    )
    contact_method = forms.ChoiceField(
        choices=[("email", "Email"), ("phone", "Phone")],
        widget=forms.RadioSelect,
    )
    interests = forms.MultipleChoiceField(
        choices=[("tech", "Technology"), ("sports", "Sports"), ("arts", "Arts")],
        widget=forms.CheckboxSelectMultiple,
    )

Using Forms in Views

The view is where the lifecycle plays out. The canonical pattern handles GET (show a blank form) and POST (validate and act) in one function.

Function-based view

# views.py
from django.shortcuts import render, redirect
from .forms import ContactForm


def contact_view(request):
    if request.method == "POST":
        form = ContactForm(request.POST)      # bound form
        if form.is_valid():
            # cleaned_data holds validated, typed values
            send_contact_email(
                name=form.cleaned_data["name"],
                email=form.cleaned_data["email"],
                message=form.cleaned_data["message"],
            )
            return redirect("contact_success")   # Post/Redirect/Get
    else:
        form = ContactForm()                   # unbound form

    return render(request, "contact.html", {"form": form})

Class-based view

For the common "show form, validate, redirect" shape, FormView (or CreateView/UpdateView for ModelForms) removes the boilerplate. You override form_valid() to do your work.

# views.py
from django.urls import reverse_lazy
from django.views.generic.edit import FormView
from .forms import ContactForm


class ContactView(FormView):
    template_name = "contact.html"
    form_class = ContactForm
    success_url = reverse_lazy("contact_success")

    def form_valid(self, form):
        send_contact_email(
            name=form.cleaned_data["name"],
            email=form.cleaned_data["email"],
            message=form.cleaned_data["message"],
        )
        return super().form_valid(form)   # performs the redirect

Rendering in Templates

Getting a form onto the page ranges from one line to fully hand-built markup.

Quick rendering

The simplest approach wraps the form in your own <form> tag and lets Django emit the fields. Modern Django (4.0+) also ships form.as_div, which is the recommended default because a <div> layout styles more cleanly than <p>.

<!-- contact.html -->
<form method="post">
    {% csrf_token %}
    {{ form.as_div }}
    <button type="submit">Send</button>
</form>

Other shortcuts exist — form.as_p, form.as_table, form.as_ul — but they only control the wrapper element.

Manual rendering

When you need full control over layout — say, to match a CSS framework — render each field by hand. You still get labels, IDs, and errors from the form object.

<form method="post">
    {% csrf_token %}

    <div class="form-group">
        {{ form.name.errors }}
        <label for="{{ form.name.id_for_label }}">Your name</label>
        {{ form.name }}
    </div>

    <div class="form-group">
        {{ form.email.errors }}
        <label for="{{ form.email.id_for_label }}">Email</label>
        {{ form.email }}
    </div>

    <div class="form-group">
        {{ form.message.errors }}
        <label for="{{ form.message.id_for_label }}">Message</label>
        {{ form.message }}
    </div>

    <button type="submit">Send message</button>
</form>

Worked Example: Conference Registration

Let's pull the pieces together into something realistic: a registration form driven by a model, with a couple of extra fields that don't live on the model and a cross-field check. (The clean() method here is a preview — the next lesson goes deep on validation.)

# models.py
from django.db import models


class Registration(models.Model):
    SHIRT_SIZES = [
        ("S", "Small"), ("M", "Medium"), ("L", "Large"), ("XL", "Extra Large"),
    ]
    MEAL_CHOICES = [
        ("regular", "Regular"), ("vegetarian", "Vegetarian"), ("vegan", "Vegan"),
    ]

    first_name = models.CharField(max_length=100)
    last_name = models.CharField(max_length=100)
    email = models.EmailField()
    company = models.CharField(max_length=200, blank=True)
    shirt_size = models.CharField(max_length=2, choices=SHIRT_SIZES)
    meal_preference = models.CharField(max_length=20, choices=MEAL_CHOICES)
    registered_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return f"{self.first_name} {self.last_name}"

# forms.py
from django import forms
from .models import Registration


class RegistrationForm(forms.ModelForm):
    # Extra fields that are not stored on the model
    confirm_email = forms.EmailField(label="Confirm email")
    accept_terms = forms.BooleanField(
        required=True, label="I accept the terms and conditions",
    )

    class Meta:
        model = Registration
        # registered_at is set automatically, so it is excluded
        fields = ["first_name", "last_name", "email", "company",
                  "shirt_size", "meal_preference"]

    def clean(self):
        cleaned = super().clean()
        if cleaned.get("email") != cleaned.get("confirm_email"):
            self.add_error("confirm_email", "Email addresses don't match.")
        return cleaned

# views.py
from django.urls import reverse_lazy
from django.views.generic.edit import CreateView
from .forms import RegistrationForm
from .models import Registration


class RegistrationCreateView(CreateView):
    model = Registration
    form_class = RegistrationForm
    template_name = "registration_form.html"
    success_url = reverse_lazy("registration_success")

Hands-on Exercise

# forms.py
from django import forms


class FeedbackForm(forms.Form):
    name = forms.CharField(max_length=100)
    email = forms.EmailField()
    rating = forms.IntegerField(
        min_value=1, max_value=5,
        widget=forms.NumberInput(attrs={"min": 1, "max": 5}),
    )
    comments = forms.CharField(required=False, widget=forms.Textarea)


# views.py
from django.shortcuts import render, redirect
from .forms import FeedbackForm


def feedback_view(request):
    if request.method == "POST":
        form = FeedbackForm(request.POST)
        if form.is_valid():
            print(form.cleaned_data)   # in real code: save or email
            return redirect("feedback_thanks")
    else:
        form = FeedbackForm()
    return render(request, "feedback.html", {"form": form})

<!-- feedback.html -->
<form method="post">
    {% csrf_token %}
    {{ form.as_div }}
    <button type="submit">Send feedback</button>
</form>

Best Practices

Summary & Quiz

📚 Further Reading

• Django docs — Working with forms
• Django docs — Creating forms from models (ModelForm)
• Django docs — Form fields reference

🚀 What's Next?

You can now build and render forms — but the real power is in validation. Next we go deep on field-level, form-level, and model-level validation, custom validators, and clean multi-field rules.