📝 Forms Handling with Flask-WTF

Why Form Libraries Exist

Handling a form by hand means juggling a lot of tedious, security-sensitive work: rendering the right HTML, reading POST data, checking every field, showing error messages, and defending against forgery. Do any of it wrong and you have a broken — or worse, exploitable — form.

Flask-WTF is a thin bridge between Flask and the WTForms library. You declare a form once as a Python class, and it handles rendering hints, validation, error collection, and CSRF tokens for you.

💡 A useful analogy: A form class is a bouncer with a guest list. You write the rules once ("name required, email must look real, message at least 10 characters"), and the bouncer checks every submission at the door, turning away bad data with a clear reason before it ever reaches your business logic.

Installing & Configuring Flask-WTF

Install the package (it pulls WTForms in as a dependency):

pip install Flask-WTF

Flask-WTF's CSRF protection and WTForms both need Flask's SECRET_KEY to sign tokens. Using the application factory pattern, load the key from the environment so it never lands in version control:

import os
from flask import Flask


def create_app():
    app = Flask(__name__)
    # In production, SECRET_KEY MUST come from the environment.
    app.config["SECRET_KEY"] = os.environ.get("SECRET_KEY", os.urandom(32))

    from .routes import main
    app.register_blueprint(main)
    return app

Defining Form Classes

A form is a Python class that subclasses FlaskForm. Each field is a class attribute; each carries a label and a list of validators:

from flask_wtf import FlaskForm
from wtforms import StringField, TextAreaField, BooleanField, SubmitField
from wtforms.validators import DataRequired, Email, Length


class ContactForm(FlaskForm):
    name = StringField("Name", validators=[DataRequired(), Length(min=2, max=50)])
    email = StringField("Email", validators=[DataRequired(), Email()])
    message = TextAreaField("Message", validators=[DataRequired(), Length(min=10)])
    subscribe = BooleanField("Subscribe to our newsletter")
    submit = SubmitField("Send message")

Fields & Validators

Common field types

Common validators

Handling Forms in Routes

In the view, instantiate the form and call validate_on_submit(). It returns True only when the request is a POST and every validator passed — the perfect single check for "is this a valid submission?"

from flask import Blueprint, render_template, redirect, url_for, flash
from .forms import ContactForm

main = Blueprint("main", __name__)


@main.route("/contact", methods=["GET", "POST"])
def contact():
    form = ContactForm()
    if form.validate_on_submit():
        # All validators passed — access data via form.<field>.data
        flash(f"Thanks, {form.name.data}! We'll reply to {form.email.data}.", "success")
        # Redirect after POST so a refresh won't resubmit the form.
        return redirect(url_for("main.contact"))
    # GET request, or validation failed: render (with errors, if any).
    return render_template("contact.html", form=form)

That redirect on success is the Post/Redirect/Get (PRG) pattern. Without it, a user who refreshes after submitting would re-POST the form and duplicate the action. Redirecting to a GET page makes refresh harmless.

Rendering Forms in Templates

In the template, {{ form.hidden_tag() }} emits the CSRF token (and any hidden fields). Each field renders its label and input; loop over field.errors to show validation messages:

{% extends "base.html" %}
{% block title %}Contact Us{% endblock %}

{% block content %}
<h1>Contact Us</h1>

{% include "partials/flashes.html" %}

<form method="post" novalidate>
    {{ form.hidden_tag() }}   {# CSRF token — required #}

    <div class="form-group">
        {{ form.name.label }}
        {{ form.name(class="form-control") }}
        {% for error in form.name.errors %}
            <span class="error">{{ error }}</span>
        {% endfor %}
    </div>

    <div class="form-group">
        {{ form.email.label }}
        {{ form.email(class="form-control") }}
        {% for error in form.email.errors %}
            <span class="error">{{ error }}</span>
        {% endfor %}
    </div>

    <div class="form-group">
        {{ form.message.label }}
        {{ form.message(class="form-control", rows=5) }}
        {% for error in form.message.errors %}
            <span class="error">{{ error }}</span>
        {% endfor %}
    </div>

    <div class="form-check">
        {{ form.subscribe() }} {{ form.subscribe.label }}
    </div>

    {{ form.submit(class="btn btn-primary") }}
</form>
{% endblock %}

{% macro render_field(field) %}
    <div class="form-group">
        {{ field.label }}
        {{ field(class="form-control") }}
        {% for error in field.errors %}
            <span class="error">{{ error }}</span>
        {% endfor %}
    </div>
{% endmacro %}

{{ render_field(form.name) }}
{{ render_field(form.email) }}
{{ render_field(form.message) }}

CSRF & Custom Validators

What CSRF protection does

Cross-Site Request Forgery tricks a logged-in user's browser into submitting a request they didn't intend — say, a hidden form on a malicious site posting to your /transfer-money route. Flask-WTF defends against this by embedding a secret, per-session token in every form via form.hidden_tag(). On submission it checks the token; a forged request from another site can't know it, so it's rejected.

<input type="hidden" name="csrf_token"
       value="IjXk9…signed…value">

Custom validators

For rules the built-ins don't cover — like a database uniqueness check — add a method named validate_<fieldname> to the form class. WTForms calls it automatically and a raised ValidationError becomes a field error:

from wtforms.validators import ValidationError
from .models import User


class RegistrationForm(FlaskForm):
    username = StringField("Username", validators=[DataRequired(), Length(min=3, max=20)])
    password = PasswordField("Password", validators=[DataRequired(), Length(min=8)])
    confirm = PasswordField(
        "Confirm password",
        validators=[DataRequired(), EqualTo("password", message="Passwords must match.")],
    )
    submit = SubmitField("Register")

    def validate_username(self, field):
        if User.query.filter_by(username=field.data).first():
            raise ValidationError("That username is already taken.")

Hands-on Exercise

from flask_wtf import FlaskForm
from wtforms import StringField, SelectField, TextAreaField, SubmitField
from wtforms.validators import DataRequired, Email, Length, Optional


class FeedbackForm(FlaskForm):
    name = StringField("Name", validators=[DataRequired(), Length(min=2, max=50)])
    email = StringField("Email", validators=[DataRequired(), Email()])
    rating = SelectField(
        "Rating",
        choices=[("5", "Excellent"), ("4", "Good"), ("3", "Okay"),
                 ("2", "Poor"), ("1", "Bad")],
        validators=[DataRequired()],
    )
    comments = TextAreaField("Comments", validators=[Optional(), Length(max=500)])
    submit = SubmitField("Send feedback")

Summary & Quiz

📚 Further Reading

• Flask-WTF Documentation
• WTForms Documentation
• Miguel Grinberg — Flask Mega-Tutorial: Web Forms

🚀 What's Next?

Your forms now collect clean, validated data — but that data needs somewhere to live. Next we'll persist it with the Flask-SQLAlchemy extension, mapping Python objects to database rows.