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.
SOCIAL SHARE CARD GENERATOR