M Saad Ahmad

Posted on Apr 24

Day 81 of #100DaysOfCode — Flask Forms

#webdev #programming #flask #100daysofcode

Yesterday I covered Jinja2 templates. Today I learned forms in Flask. This is where the difference between Flask and Django becomes most obvious. Django gave us ModelForm, UserCreationForm, built-in validation, and CSRF protection all out of the box. Flask gives us none of that. You either handle forms manually or bring in a library. Today I covered both approaches.

The Manual Approach

Before using any library, it's worth understanding what handling a form manually in Flask actually looks like:

from flask import Flask, request, render_template, redirect, url_for

app = Flask(__name__)

@app.route('/contact', methods=['GET', 'POST'])
def contact():
    error = None
    if request.method == 'POST':
        name = request.form.get('name', '').strip()
        email = request.form.get('email', '').strip()
        message = request.form.get('message', '').strip()

        if not name:
            error = 'Name is required'
        elif not email or '@' not in email:
            error = 'Valid email is required'
        elif not message:
            error = 'Message is required'
        else:
            # process the form
            return redirect(url_for('home'))

    return render_template('contact.html', error=error)

This works but has problems. Validation logic is manual and repetitive. Error messages are basic. There's no CSRF protection. Scaling this across many forms gets messy fast. This is exactly why WTForms exists.

Flask-WTF and WTForms

Flask-WTF is a Flask extension that wraps WTForms and adds Flask-specific features, most importantly, CSRF protection built in.

pip install flask-wtf

Flask-WTF requires a secret key for CSRF token generation:

app = Flask(__name__)
app.config['SECRET_KEY'] = 'your-secret-key-here'

Creating a Form

from flask_wtf import FlaskForm
from wtforms import StringField, TextAreaField, EmailField, PasswordField, BooleanField, SelectField
from wtforms.validators import DataRequired, Email, Length, EqualTo, Optional

class ContactForm(FlaskForm):
    name = StringField('Name', validators=[DataRequired(), Length(min=2, max=100)])
    email = EmailField('Email', validators=[DataRequired(), Email()])
    message = TextAreaField('Message', validators=[DataRequired(), Length(min=10)])

FlaskForm is the base class equivalent to Django's forms.Form. Each field is a class attribute. Validators are passed as a list to each field.

Common Field Types

from wtforms import (
    StringField,
    TextAreaField,
    EmailField,
    PasswordField,
    IntegerField,
    FloatField,
    BooleanField,
    SelectField,
    SelectMultipleField,
    FileField,
    HiddenField,
    DateField,
)

Field	Use
`StringField`	Single line text
`TextAreaField`	Multi-line text
`EmailField`	Email with basic validation
`PasswordField`	Password input, hides text
`IntegerField`	Integer number
`BooleanField`	Checkbox
`SelectField`	Dropdown
`FileField`	File upload
`DateField`	Date input

Common Validators

from wtforms.validators import (
    DataRequired,    # field cannot be empty
    Optional,        # field is optional
    Email,           # must be a valid email format
    Length,          # min/max length
    NumberRange,     # min/max number value
    EqualTo,         # must match another field for password confirmation
    URL,             # must be a valid URL
    Regexp,          # must match a regex pattern
)

class RegisterForm(FlaskForm):
    username = StringField('Username', validators=[
        DataRequired(),
        Length(min=3, max=50)
    ])
    email = EmailField('Email', validators=[
        DataRequired(),
        Email()
    ])
    password = PasswordField('Password', validators=[
        DataRequired(),
        Length(min=8)
    ])
    confirm_password = PasswordField('Confirm Password', validators=[
        DataRequired(),
        EqualTo('password', message='Passwords must match')
    ])

EqualTo('password') references the password field by name and checks they match, same as Django's UserCreationForm password confirmation logic, but explicit.

Handling Forms in Views

@app.route('/register', methods=['GET', 'POST'])
def register():
    form = RegisterForm()
    if form.validate_on_submit():
        username = form.username.data
        email = form.email.data
        password = form.password.data
        # create the user, then redirect
        return redirect(url_for('login'))
    return render_template('register.html', form=form)

form.validate_on_submit() is Flask-WTF's shortcut; it checks that the request is POST and that all validators pass. Equivalent to Django's if request.method == 'POST': form = Form(request.POST); if form.is_valid():. One line instead of three.

After validation passes, access field values through form.fieldname.data.

Rendering Forms in Templates

Quick render — all fields at once

<!-- templates/register.html -->
{% extends 'base.html' %}

{% block content %}
<h1>Register</h1>
<form method="post">
    {{ form.hidden_tag() }}
    {{ form.username.label }} {{ form.username() }}
    {{ form.email.label }} {{ form.email() }}
    {{ form.password.label }} {{ form.password() }}
    {{ form.confirm_password.label }} {{ form.confirm_password() }}
    <button type="submit">Register</button>
</form>
{% endblock %}

{{ form.hidden_tag() }} renders the CSRF token as a hidden input field. Without this, Flask-WTF rejects every POST request. This is the Flask equivalent of Django's {% csrf_token %}.

{{ form.username() }} renders the input field. {{ form.username.label }} renders the label.

Rendering with error messages

<form method="post">
    {{ form.hidden_tag() }}

    <div>
        {{ form.username.label }}
        {{ form.username(placeholder='Enter username') }}
        {% for error in form.username.errors %}
            <span class="error">{{ error }}</span>
        {% endfor %}
    </div>

    <div>
        {{ form.email.label }}
        {{ form.email(placeholder='Enter email') }}
        {% for error in form.email.errors %}
            <span class="error">{{ error }}</span>
        {% endfor %}
    </div>

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

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

    <button type="submit">Register</button>
</form>

form.fieldname.errors is a list of validation error messages for that field. Loop over them and display each one. Same concept as Django's form.field.errors.

Passing HTML attributes

{{ form.username(class='form-input', placeholder='Enter username', autofocus=True) }}

Pass any HTML attribute as a keyword argument to the field call. Flask-WTF renders them on the input element.

Flash Messages

Flash messages are one-time messages shown after a redirect, "Registration successful", "Invalid credentials", etc. Flask has built-in flash support:

from flask import flash, redirect, url_for

@app.route('/register', methods=['GET', 'POST'])
def register():
    form = RegisterForm()
    if form.validate_on_submit():
        # create user...
        flash('Account created successfully. Please log in.', 'success')
        return redirect(url_for('login'))
    return render_template('register.html', form=form)

flash(message, category) stores the message in the session for the next request. Categories are arbitrary strings: success, error, warning, info, you use them for styling.

Display them in base.html:

{% with messages = get_flashed_messages(with_categories=True) %}
    {% if messages %}
        {% for category, message in messages %}
            <div class="alert alert-{{ category }}">
                {{ message }}
            </div>
        {% endfor %}
    {% endif %}
{% endwith %}

get_flashed_messages(with_categories=True) returns a list of (category, message) tuples. Put this in base.html so flash messages appear on every page after a redirect.

Custom Validation

Field-level validation

Add a method named validate_<fieldname> to the form class:

class RegisterForm(FlaskForm):
    username = StringField('Username', validators=[DataRequired()])

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

This runs automatically when validate_on_submit() is called, same as Django's clean_<fieldname>() method.

Form-level validation

Override the validate method for cross-field validation:

from wtforms import ValidationError

class LoginForm(FlaskForm):
    email = EmailField('Email', validators=[DataRequired(), Email()])
    password = PasswordField('Password', validators=[DataRequired()])

    def validate(self, extra_validators=None):
        if not super().validate(extra_validators):
            return False
        user = User.query.filter_by(email=self.email.data).first()
        if not user or not user.check_password(self.password.data):
            self.email.errors.append('Invalid email or password.')
            return False
        return True

SelectField — Dropdowns

class JobForm(FlaskForm):
    job_type = SelectField('Job Type', choices=[
        ('full_time', 'Full Time'),
        ('part_time', 'Part Time'),
        ('remote', 'Remote'),
        ('contract', 'Contract'),
    ], validators=[DataRequired()])

choices is a list of (value, label) tuples, same as Django's choices on a model field. The value is what gets submitted, the label is what the user sees.

For dynamic choices populated from the database:

class AssignForm(FlaskForm):
    user = SelectField('Assign To', coerce=int)

@app.route('/assign')
def assign():
    form = AssignForm()
    form.user.choices = [(u.id, u.username) for u in User.query.all()]
    return render_template('assign.html', form=form)

coerce=int tells WTForms to convert the submitted string value to an integer, important when the value is a database ID.

File Upload with Flask-WTF

from flask_wtf.file import FileField, FileRequired, FileAllowed

class UploadForm(FlaskForm):
    avatar = FileField('Profile Picture', validators=[
        FileRequired(),
        FileAllowed(['jpg', 'jpeg', 'png'], 'Images only.')
    ])

import os
from werkzeug.utils import secure_filename

@app.route('/upload', methods=['GET', 'POST'])
def upload():
    form = UploadForm()
    if form.validate_on_submit():
        file = form.avatar.data
        filename = secure_filename(file.filename)
        file.save(os.path.join('static/uploads', filename))
        return redirect(url_for('home'))
    return render_template('upload.html', form=form)

secure_filename sanitizes the filename to prevent directory traversal attacks. FileAllowed restricts accepted file extensions. The form template needs enctype="multipart/form-data" just like in Django.

Flask-WTF vs Django Forms — Side by Side

Django	Flask-WTF
`forms.Form`	`FlaskForm`
`forms.ModelForm`	No direct equivalent — forms are separate from models
`CharField`	`StringField`
`EmailField`	`EmailField`
`{% csrf_token %}`	`{{ form.hidden_tag() }}`
`form.is_valid()`	`form.validate_on_submit()`
`form.cleaned_data['field']`	`form.field.data`
`clean_fieldname()`	`validate_fieldname()`
`form.field.errors`	`form.field.errors`
Flash messages	`flash()` + `get_flashed_messages()`

The biggest difference: Django's ModelForm generates form fields automatically from a model. WTForms has no equivalent; you define form fields manually, separate from your database models. More work, but also more explicit control.

Wrapping Up

Forms in Flask require more setup than Django, but the pattern is clean once it's in place. Flask-WTF handles CSRF, WTForms handles validation and field rendering, and flash messages handle feedback after redirects. The pieces fit together well, even if they don't come pre-assembled.

DEV Community