Forms are the primary interface between your users and your application. Every login page, registration flow, search bar, checkout form, and settings panel depends on form handling done right. Get it wrong and you open the door to data corruption, security vulnerabilities, and frustrated users.
Flask gives you two approaches to form handling:
request.form, and validate everything manually. Fine for a single input, tedious and error-prone for anything more.This tutorial covers both approaches in depth. We start with raw form handling so you understand what Flask-WTF abstracts away, then move into the full Flask-WTF workflow including field types, validators, file uploads, dynamic forms, AJAX submission, and several practical examples you can drop into real projects.
Before reaching for any library, you should understand how Flask handles forms natively. This gives you the foundation to debug issues when they arise and appreciate what Flask-WTF does for you.
Here is a minimal login form submitted via POST:
<!-- templates/login_raw.html -->
<form method="POST" action="/login">
<div>
<label for="username">Username</label>
<input type="text" id="username" name="username" required>
</div>
<div>
<label for="password">Password</label>
<input type="password" id="password" name="password" required>
</div>
<button type="submit">Log In</button>
</form>
The route must accept both GET (display the form) and POST (process the submission):
from flask import Flask, request, render_template, redirect, url_for, flash
app = Flask(__name__)
app.secret_key = 'your-secret-key-here'
@app.route('/login', methods=['GET', 'POST'])
def login():
if request.method == 'POST':
username = request.form.get('username', '').strip()
password = request.form.get('password', '')
# Manual validation
errors = []
if not username:
errors.append('Username is required.')
if not password:
errors.append('Password is required.')
if len(password) < 8:
errors.append('Password must be at least 8 characters.')
if errors:
for error in errors:
flash(error, 'danger')
return render_template('login_raw.html', username=username)
# Authentication logic here
if authenticate(username, password):
flash('Welcome back!', 'success')
return redirect(url_for('dashboard'))
else:
flash('Invalid credentials.', 'danger')
return render_template('login_raw.html', username=username)
return render_template('login_raw.html')
Flash messages provide one-time feedback to the user. Display them in your template:
<!-- templates/base.html (partial) -->
{% 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 %}
This approach works, but it has significant drawbacks:
strip() or escape() and you have a bug or vulnerability.Flask-WTF solves all of these problems.
pip install Flask-WTF
This installs both Flask-WTF and its dependency WTForms.
Flask-WTF requires a SECRET_KEY for CSRF token generation:
import os
from flask import Flask
app = Flask(__name__)
# REQUIRED: Used to sign CSRF tokens and session cookies
app.config['SECRET_KEY'] = os.environ.get('SECRET_KEY', 'dev-key-change-in-production')
# Optional Flask-WTF settings
app.config['WTF_CSRF_ENABLED'] = True # Default: True
app.config['WTF_CSRF_TIME_LIMIT'] = 3600 # Token expiry in seconds (default: 3600)
app.config['WTF_CSRF_SSL_STRICT'] = True # Strict referer checking for HTTPS
app.config['MAX_CONTENT_LENGTH'] = 16 * 1024 * 1024 # 16 MB upload limit
Cross-Site Request Forgery (CSRF) tricks a user's browser into submitting a form to your site using their authenticated session. Flask-WTF prevents this by:
In your templates, always include the CSRF token:
<form method="POST">
{{ form.hidden_tag() }}
<!-- or individually: {{ form.csrf_token }} -->
<!-- rest of the form -->
</form>
For AJAX requests, you can include the token in a meta tag and send it as a header:
<meta name="csrf-token" content="{{ csrf_token() }}">
# JavaScript
fetch('/api/submit', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-CSRFToken': document.querySelector('meta[name="csrf-token"]').content
},
body: JSON.stringify(data)
});
WTForms provides a rich set of field types. Here is a comprehensive reference with practical usage for each.
from flask_wtf import FlaskForm
from wtforms import StringField, PasswordField, TextAreaField, HiddenField
from wtforms.validators import DataRequired, Length, Email
class ProfileForm(FlaskForm):
# Basic text input
username = StringField('Username', validators=[
DataRequired(),
Length(min=3, max=80)
])
# Renders as <input type="email">
email = StringField('Email', validators=[
DataRequired(),
Email(message='Enter a valid email address.')
])
# Renders as <input type="password">
password = PasswordField('Password', validators=[
DataRequired(),
Length(min=8, message='Password must be at least 8 characters.')
])
# Renders as <textarea>
bio = TextAreaField('Bio', validators=[
Length(max=500)
])
# Hidden field — not shown to users
user_id = HiddenField('User ID')
from wtforms import IntegerField, FloatField, DecimalField
from wtforms.validators import NumberRange
class ProductForm(FlaskForm):
quantity = IntegerField('Quantity', validators=[
DataRequired(),
NumberRange(min=1, max=1000, message='Quantity must be between 1 and 1000.')
])
price = FloatField('Price', validators=[
DataRequired(),
NumberRange(min=0.01)
])
# DecimalField for precise financial calculations
tax_rate = DecimalField('Tax Rate (%)', places=2, validators=[
NumberRange(min=0, max=100)
])
from wtforms import SelectField, RadioField, SelectMultipleField
class OrderForm(FlaskForm):
# Dropdown select
country = SelectField('Country', choices=[
('', '-- Select Country --'),
('us', 'United States'),
('uk', 'United Kingdom'),
('ca', 'Canada'),
('au', 'Australia')
], validators=[DataRequired()])
# Radio buttons
shipping = RadioField('Shipping Method', choices=[
('standard', 'Standard (5-7 days)'),
('express', 'Express (2-3 days)'),
('overnight', 'Overnight')
], default='standard')
# Multi-select (hold Ctrl/Cmd to select multiple)
interests = SelectMultipleField('Interests', choices=[
('tech', 'Technology'),
('science', 'Science'),
('art', 'Art')
])
from wtforms import BooleanField, DateField, DateTimeLocalField
class EventForm(FlaskForm):
# Checkbox
agree_terms = BooleanField('I agree to the terms and conditions', validators=[
DataRequired(message='You must accept the terms.')
])
# Date picker
event_date = DateField('Event Date', format='%Y-%m-%d', validators=[
DataRequired()
])
# DateTime picker
starts_at = DateTimeLocalField('Starts At', format='%Y-%m-%dT%H:%M')
from flask_wtf.file import FileField, FileAllowed, FileRequired, MultipleFileField
class UploadForm(FlaskForm):
# Single file upload
avatar = FileField('Profile Picture', validators=[
FileRequired(),
FileAllowed(['jpg', 'png', 'gif'], 'Images only!')
])
# Multiple file upload
documents = MultipleFileField('Documents', validators=[
FileAllowed(['pdf', 'doc', 'docx'], 'Documents only!')
])
from wtforms import SubmitField
class ContactForm(FlaskForm):
name = StringField('Name', validators=[DataRequired()])
message = TextAreaField('Message', validators=[DataRequired()])
submit = SubmitField('Send Message')
| Field | HTML Output | Use Case |
|---|---|---|
StringField |
<input type="text"> |
Names, usernames, short text |
PasswordField |
<input type="password"> |
Passwords, secrets |
TextAreaField |
<textarea> |
Long text, comments, bios |
IntegerField |
<input type="number"> |
Whole numbers, quantities |
FloatField |
<input type="number"> |
Decimal numbers, prices |
DecimalField |
<input type="text"> |
Precise decimals, currency |
BooleanField |
<input type="checkbox"> |
Agree/disagree, toggles |
SelectField |
<select> |
Dropdowns |
RadioField |
<input type="radio"> |
Single choice from few options |
SelectMultipleField |
<select multiple> |
Multiple selections |
DateField |
<input type="text"> |
Date input |
DateTimeLocalField |
<input type="datetime-local"> |
Date + time input |
FileField |
<input type="file"> |
Single file upload |
MultipleFileField |
<input type="file" multiple> |
Multiple file upload |
HiddenField |
<input type="hidden"> |
Passing data without UI |
SubmitField |
<input type="submit"> |
Form submission button |
Validators are the backbone of form security and data integrity. WTForms ships with a solid set of built-in validators, and you can write custom ones for business-specific rules.
from wtforms.validators import (
DataRequired, # Field must not be empty
InputRequired, # Field must have input (stricter than DataRequired)
Length, # String length between min and max
Email, # Valid email format
EqualTo, # Must match another field (password confirmation)
NumberRange, # Number between min and max
Optional, # Field is optional — skip other validators if empty
URL, # Valid URL format
UUID, # Valid UUID format
Regexp, # Must match a regex pattern
AnyOf, # Value must be in a list
NoneOf, # Value must NOT be in a list
MacAddress, # Valid MAC address
IPAddress, # Valid IP address
)
class RegistrationForm(FlaskForm):
username = StringField('Username', validators=[
DataRequired(),
Length(min=3, max=25),
Regexp(r'^[A-Za-z][A-Za-z0-9_.]*$',
message='Username must start with a letter and contain only letters, numbers, dots, and underscores.')
])
email = StringField('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.')
])
age = IntegerField('Age', validators=[
Optional(),
NumberRange(min=13, max=120)
])
website = StringField('Website', validators=[
Optional(),
URL(message='Enter a valid URL.')
])
role = SelectField('Role', choices=['user', 'admin'], validators=[
AnyOf(['user', 'admin'])
])
For business rules specific to a single field, define a validate_<fieldname> method on the form class:
from wtforms import ValidationError
from models import User
class RegistrationForm(FlaskForm):
username = StringField('Username', validators=[DataRequired(), Length(min=3, max=25)])
email = StringField('Email', validators=[DataRequired(), Email()])
def validate_username(self, field):
"""Check that username is not already taken."""
user = User.query.filter_by(username=field.data).first()
if user:
raise ValidationError('That username is already taken.')
def validate_email(self, field):
"""Check that email is not already registered."""
user = User.query.filter_by(email=field.data).first()
if user:
raise ValidationError('An account with that email already exists.')
If you need the same validation logic across multiple forms, create a standalone validator function:
from wtforms import ValidationError
import re
def strong_password(form, field):
"""Enforce password complexity rules."""
password = field.data
if not re.search(r'[A-Z]', password):
raise ValidationError('Password must contain at least one uppercase letter.')
if not re.search(r'[a-z]', password):
raise ValidationError('Password must contain at least one lowercase letter.')
if not re.search(r'[0-9]', password):
raise ValidationError('Password must contain at least one digit.')
if not re.search(r'[!@#$%^&*(),.?":{}|<>]', password):
raise ValidationError('Password must contain at least one special character.')
def unique_field(model, column, message='This value is already in use.'):
"""Factory that returns a validator checking database uniqueness."""
def _validate(form, field):
existing = model.query.filter(column == field.data).first()
if existing:
raise ValidationError(message)
return _validate
# Usage
class SignupForm(FlaskForm):
username = StringField('Username', validators=[
DataRequired(),
unique_field(User, User.username, 'Username taken.')
])
password = PasswordField('Password', validators=[
DataRequired(),
Length(min=8),
strong_password
])
Override the validate method for cross-field validation:
class DateRangeForm(FlaskForm):
start_date = DateField('Start Date', validators=[DataRequired()])
end_date = DateField('End Date', validators=[DataRequired()])
def validate(self, extra_validators=None):
"""Ensure end date is after start date."""
if not super().validate(extra_validators=extra_validators):
return False
if self.end_date.data <= self.start_date.data:
self.end_date.errors.append('End date must be after start date.')
return False
return True
Each field on a form object is callable and renders the corresponding HTML element:
<!-- templates/register.html -->
{% extends "base.html" %}
{% block content %}
<h1>Register</h1>
<form method="POST" novalidate>
{{ form.hidden_tag() }}
<div class="form-group">
{{ form.username.label(class="form-label") }}
{{ form.username(class="form-control", placeholder="Choose a username") }}
{% if form.username.errors %}
{% for error in form.username.errors %}
<small class="text-danger">{{ error }}</small>
{% endfor %}
{% endif %}
</div>
<div class="form-group">
{{ form.email.label(class="form-label") }}
{{ form.email(class="form-control", placeholder="you@example.com") }}
{% if form.email.errors %}
{% for error in form.email.errors %}
<small class="text-danger">{{ error }}</small>
{% endfor %}
{% endif %}
</div>
<div class="form-group">
{{ form.password.label(class="form-label") }}
{{ form.password(class="form-control") }}
{% if form.password.errors %}
{% for error in form.password.errors %}
<small class="text-danger">{{ error }}</small>
{% endfor %}
{% endif %}
</div>
{{ form.submit(class="btn btn-primary") }}
</form>
{% endblock %}
Conditionally apply Bootstrap's is-invalid class to highlight fields with errors:
<div class="form-group">
{{ form.email.label(class="form-label") }}
{{ form.email(class="form-control" + (" is-invalid" if form.email.errors else "")) }}
{% for error in form.email.errors %}
<div class="invalid-feedback">{{ error }}</div>
{% endfor %}
</div>
Instead of repeating the same field rendering pattern for every field, define a macro:
<!-- templates/macros/forms.html -->
{% macro render_field(field, placeholder='') %}
<div class="mb-3">
{{ field.label(class="form-label") }}
{% if field.type == 'BooleanField' %}
<div class="form-check">
{{ field(class="form-check-input" + (" is-invalid" if field.errors else "")) }}
{{ field.label(class="form-check-label") }}
</div>
{% elif field.type == 'TextAreaField' %}
{{ field(class="form-control" + (" is-invalid" if field.errors else ""), rows=5, placeholder=placeholder) }}
{% elif field.type == 'SelectField' %}
{{ field(class="form-select" + (" is-invalid" if field.errors else "")) }}
{% elif field.type == 'FileField' %}
{{ field(class="form-control" + (" is-invalid" if field.errors else "")) }}
{% else %}
{{ field(class="form-control" + (" is-invalid" if field.errors else ""), placeholder=placeholder) }}
{% endif %}
{% for error in field.errors %}
<div class="invalid-feedback d-block">{{ error }}</div>
{% endfor %}
</div>
{% endmacro %}
Now rendering any form becomes trivial:
<!-- templates/register.html -->
{% from "macros/forms.html" import render_field %}
{% extends "base.html" %}
{% block content %}
<h1>Register</h1>
<form method="POST" novalidate>
{{ form.hidden_tag() }}
{{ render_field(form.username, placeholder='Choose a username') }}
{{ render_field(form.email, placeholder='you@example.com') }}
{{ render_field(form.password) }}
{{ render_field(form.confirm_password) }}
{{ render_field(form.agree_terms) }}
{{ form.submit(class="btn btn-primary") }}
</form>
{% endblock %}
File uploads require special handling: the form must use multipart/form-data encoding, files must be validated for type and size, and filenames must be sanitized before saving to disk.
from flask_wtf import FlaskForm
from flask_wtf.file import FileField, FileAllowed, FileRequired
from wtforms import StringField, SubmitField
from wtforms.validators import DataRequired
class AvatarUploadForm(FlaskForm):
username = StringField('Username', validators=[DataRequired()])
avatar = FileField('Profile Picture', validators=[
FileRequired(message='Please select a file.'),
FileAllowed(['jpg', 'jpeg', 'png', 'gif'], 'Images only (jpg, png, gif).')
])
submit = SubmitField('Upload')
import os
from flask import Flask, render_template, redirect, url_for, flash, current_app
from werkzeug.utils import secure_filename
import uuid
app = Flask(__name__)
app.config['SECRET_KEY'] = 'your-secret-key'
app.config['UPLOAD_FOLDER'] = os.path.join(app.root_path, 'static', 'uploads')
app.config['MAX_CONTENT_LENGTH'] = 16 * 1024 * 1024 # 16 MB max
# Ensure upload directory exists
os.makedirs(app.config['UPLOAD_FOLDER'], exist_ok=True)
def save_file(file_storage, subfolder=''):
"""Save an uploaded file with a unique name. Returns the saved filename."""
original = secure_filename(file_storage.filename)
# Prevent empty filename after sanitization
if not original:
original = 'upload'
ext = original.rsplit('.', 1)[-1].lower() if '.' in original else 'bin'
unique_name = f"{uuid.uuid4().hex}.{ext}"
save_path = os.path.join(current_app.config['UPLOAD_FOLDER'], subfolder)
os.makedirs(save_path, exist_ok=True)
file_storage.save(os.path.join(save_path, unique_name))
return unique_name
@app.route('/upload', methods=['GET', 'POST'])
def upload_avatar():
form = AvatarUploadForm()
if form.validate_on_submit():
filename = save_file(form.avatar.data, subfolder='avatars')
flash(f'Avatar uploaded: {filename}', 'success')
return redirect(url_for('upload_avatar'))
return render_template('upload.html', form=form)
<!-- templates/upload.html -->
{% extends "base.html" %}
{% block content %}
<h1>Upload Avatar</h1>
<form method="POST" enctype="multipart/form-data" novalidate>
{{ form.hidden_tag() }}
<div class="mb-3">
{{ form.username.label(class="form-label") }}
{{ form.username(class="form-control") }}
</div>
<div class="mb-3">
{{ form.avatar.label(class="form-label") }}
{{ form.avatar(class="form-control") }}
{% for error in form.avatar.errors %}
<div class="text-danger">{{ error }}</div>
{% endfor %}
</div>
<!-- Image preview -->
<div class="mb-3">
<img id="preview" src="#" alt="Preview" style="display:none; max-width:200px;" class="img-thumbnail">
</div>
{{ form.submit(class="btn btn-primary") }}
</form>
<script>
document.getElementById('avatar').addEventListener('change', function(e) {
const preview = document.getElementById('preview');
const file = e.target.files[0];
if (file) {
const reader = new FileReader();
reader.onload = function(e) {
preview.src = e.target.result;
preview.style.display = 'block';
};
reader.readAsDataURL(file);
}
});
</script>
{% endblock %}
from flask_wtf.file import MultipleFileField, FileAllowed
class DocumentUploadForm(FlaskForm):
documents = MultipleFileField('Upload Documents', validators=[
FileAllowed(['pdf', 'doc', 'docx', 'txt'], 'Documents only.')
])
submit = SubmitField('Upload All')
@app.route('/upload-docs', methods=['GET', 'POST'])
def upload_documents():
form = DocumentUploadForm()
if form.validate_on_submit():
saved = []
for file in form.documents.data:
if file.filename: # Skip empty file inputs
filename = save_file(file, subfolder='documents')
saved.append(filename)
flash(f'Uploaded {len(saved)} document(s).', 'success')
return redirect(url_for('upload_documents'))
return render_template('upload_docs.html', form=form)
Static form classes work for most cases. But sometimes you need forms that adapt at runtime — choices loaded from a database, fields added or removed based on user action, or nested sub-forms.
class AssignTaskForm(FlaskForm):
title = StringField('Task Title', validators=[DataRequired()])
assignee = SelectField('Assign To', coerce=int, validators=[DataRequired()])
submit = SubmitField('Create Task')
@app.route('/tasks/new', methods=['GET', 'POST'])
def new_task():
form = AssignTaskForm()
# Populate choices from database — MUST happen before validate_on_submit()
users = User.query.order_by(User.name).all()
form.assignee.choices = [(u.id, u.name) for u in users]
if form.validate_on_submit():
task = Task(title=form.title.data, assignee_id=form.assignee.data)
db.session.add(task)
db.session.commit()
flash('Task created.', 'success')
return redirect(url_for('task_list'))
return render_template('new_task.html', form=form)
Key point: Set form.assignee.choices before calling validate_on_submit(). Otherwise WTForms cannot validate the submitted value against the list of valid choices and the form will always fail validation.
FormField lets you embed one form inside another. Useful for address blocks, configuration sections, or any repeated structure:
from wtforms import FormField, Form
# Note: sub-form inherits from wtforms.Form, NOT FlaskForm
# (FlaskForm adds its own CSRF token — you only want one per outer form)
class AddressForm(Form):
street = StringField('Street', validators=[DataRequired()])
city = StringField('City', validators=[DataRequired()])
state = StringField('State', validators=[DataRequired(), Length(min=2, max=2)])
zip_code = StringField('ZIP Code', validators=[
DataRequired(),
Regexp(r'^\d{5}(-\d{4})?$', message='Invalid ZIP code.')
])
class CheckoutForm(FlaskForm):
full_name = StringField('Full Name', validators=[DataRequired()])
billing_address = FormField(AddressForm, label='Billing Address')
shipping_address = FormField(AddressForm, label='Shipping Address')
same_as_billing = BooleanField('Shipping same as billing')
submit = SubmitField('Place Order')
In the template, access nested fields with dot notation:
<fieldset>
<legend>Billing Address</legend>
{{ render_field(form.billing_address.street) }}
{{ render_field(form.billing_address.city) }}
{{ render_field(form.billing_address.state) }}
{{ render_field(form.billing_address.zip_code) }}
</fieldset>
Use FieldList when the number of fields is not known at class definition time:
from wtforms import FieldList, FormField, Form
class IngredientForm(Form):
name = StringField('Ingredient', validators=[DataRequired()])
quantity = StringField('Quantity', validators=[DataRequired()])
class RecipeForm(FlaskForm):
title = StringField('Recipe Title', validators=[DataRequired()])
ingredients = FieldList(FormField(IngredientForm), min_entries=1)
submit = SubmitField('Save Recipe')
@app.route('/recipes/new', methods=['GET', 'POST'])
def new_recipe():
form = RecipeForm()
if form.validate_on_submit():
recipe = Recipe(title=form.title.data)
for entry in form.ingredients.entries:
ingredient = Ingredient(
name=entry.data['name'],
quantity=entry.data['quantity']
)
recipe.ingredients.append(ingredient)
db.session.add(recipe)
db.session.commit()
flash('Recipe saved!', 'success')
return redirect(url_for('recipe_list'))
return render_template('new_recipe.html', form=form)
Add a button in the template to dynamically add more ingredient rows with JavaScript:
<div id="ingredients">
{% for entry in form.ingredients %}
<div class="ingredient-row row mb-2">
<div class="col">{{ entry.name(class="form-control", placeholder="Ingredient") }}</div>
<div class="col">{{ entry.quantity(class="form-control", placeholder="Quantity") }}</div>
<div class="col-auto">
<button type="button" class="btn btn-danger remove-row">Remove</button>
</div>
</div>
{% endfor %}
</div>
<button type="button" id="add-ingredient" class="btn btn-secondary mb-3">+ Add Ingredient</button>
<script>
let ingredientIndex = {{ form.ingredients | length }};
document.getElementById('add-ingredient').addEventListener('click', function() {
const container = document.getElementById('ingredients');
const row = document.createElement('div');
row.className = 'ingredient-row row mb-2';
row.innerHTML = `
<div class="col">
<input class="form-control" name="ingredients-${ingredientIndex}-name" placeholder="Ingredient">
</div>
<div class="col">
<input class="form-control" name="ingredients-${ingredientIndex}-quantity" placeholder="Quantity">
</div>
<div class="col-auto">
<button type="button" class="btn btn-danger remove-row">Remove</button>
</div>
`;
container.appendChild(row);
ingredientIndex++;
});
document.getElementById('ingredients').addEventListener('click', function(e) {
if (e.target.classList.contains('remove-row')) {
e.target.closest('.ingredient-row').remove();
}
});
</script>
Sometimes you want to submit a form without a full page reload — think inline editing, live search, or chat interfaces. Flask-WTF works fine with AJAX; you just need to handle the CSRF token and return JSON instead of HTML.
from flask import jsonify, request
class QuickNoteForm(FlaskForm):
content = TextAreaField('Note', validators=[
DataRequired(),
Length(max=500)
])
@app.route('/api/notes', methods=['POST'])
def create_note():
form = QuickNoteForm()
if form.validate_on_submit():
note = Note(content=form.content.data)
db.session.add(note)
db.session.commit()
return jsonify({
'success': True,
'note': {
'id': note.id,
'content': note.content,
'created_at': note.created_at.isoformat()
}
}), 201
# Return validation errors as JSON
return jsonify({
'success': False,
'errors': form.errors
}), 400
<meta name="csrf-token" content="{{ csrf_token() }}">
<form id="note-form">
<textarea id="note-content" class="form-control" placeholder="Write a note..."></textarea>
<div id="note-errors" class="text-danger mt-1"></div>
<button type="submit" class="btn btn-primary mt-2">Save Note</button>
</form>
<div id="notes-list"></div>
<script>
const csrfToken = document.querySelector('meta[name="csrf-token"]').content;
document.getElementById('note-form').addEventListener('submit', async function(e) {
e.preventDefault();
const content = document.getElementById('note-content').value;
const errorsDiv = document.getElementById('note-errors');
errorsDiv.textContent = '';
try {
const response = await fetch('/api/notes', {
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
'X-CSRFToken': csrfToken
},
body: new URLSearchParams({ content: content })
});
const data = await response.json();
if (data.success) {
// Append the new note to the list
const notesList = document.getElementById('notes-list');
const noteEl = document.createElement('div');
noteEl.className = 'alert alert-info';
noteEl.textContent = data.note.content;
notesList.prepend(noteEl);
// Clear the form
document.getElementById('note-content').value = '';
} else {
// Display validation errors
const messages = Object.values(data.errors).flat();
errorsDiv.textContent = messages.join(' ');
}
} catch (err) {
errorsDiv.textContent = 'Network error. Please try again.';
}
});
</script>
If you have a pure REST API authenticated with tokens (not cookies), CSRF protection is not needed and can be selectively disabled:
from flask_wtf.csrf import CSRFProtect
csrf = CSRFProtect(app)
# Exempt a specific view
@csrf.exempt
@app.route('/webhook', methods=['POST'])
def webhook():
# This endpoint receives webhooks from external services
data = request.get_json()
# process webhook...
return jsonify({'status': 'ok'})
# Or exempt an entire blueprint
from flask import Blueprint
api_bp = Blueprint('api', __name__, url_prefix='/api/v1')
csrf.exempt(api_bp)
This example ties together field types, validators, custom validation, and template rendering into a production-ready registration flow.
# forms.py
from flask_wtf import FlaskForm
from wtforms import (StringField, PasswordField, BooleanField,
SelectField, SubmitField)
from wtforms.validators import (DataRequired, Length, Email,
EqualTo, Regexp, ValidationError)
from models import User
class RegistrationForm(FlaskForm):
first_name = StringField('First Name', validators=[
DataRequired(), Length(max=50)
])
last_name = StringField('Last Name', validators=[
DataRequired(), Length(max=50)
])
username = StringField('Username', validators=[
DataRequired(),
Length(min=3, max=25),
Regexp(r'^[a-zA-Z][a-zA-Z0-9_]*$',
message='Letters, numbers, and underscores only. Must start with a letter.')
])
email = StringField('Email', validators=[
DataRequired(), Email()
])
password = PasswordField('Password', validators=[
DataRequired(),
Length(min=8, message='At least 8 characters.')
])
confirm_password = PasswordField('Confirm Password', validators=[
DataRequired(),
EqualTo('password', message='Passwords must match.')
])
country = SelectField('Country', choices=[
('', '-- Select --'), ('us', 'United States'),
('uk', 'United Kingdom'), ('ca', 'Canada')
], validators=[DataRequired()])
agree_terms = BooleanField('I agree to the Terms of Service', validators=[
DataRequired(message='You must accept the terms.')
])
submit = SubmitField('Create Account')
def validate_username(self, field):
if User.query.filter_by(username=field.data).first():
raise ValidationError('Username already taken.')
def validate_email(self, field):
if User.query.filter_by(email=field.data).first():
raise ValidationError('Email already registered.')
# routes.py
from flask import render_template, redirect, url_for, flash
from werkzeug.security import generate_password_hash
from forms import RegistrationForm
from models import db, User
@app.route('/register', methods=['GET', 'POST'])
def register():
form = RegistrationForm()
if form.validate_on_submit():
user = User(
first_name=form.first_name.data,
last_name=form.last_name.data,
username=form.username.data,
email=form.email.data.lower(),
password_hash=generate_password_hash(form.password.data),
country=form.country.data
)
db.session.add(user)
db.session.commit()
flash('Account created! Please log in.', 'success')
return redirect(url_for('login'))
return render_template('register.html', form=form)
<!-- templates/register.html -->
{% from "macros/forms.html" import render_field %}
{% extends "base.html" %}
{% block content %}
<div class="row justify-content-center">
<div class="col-md-6">
<h1 class="mb-4">Create Account</h1>
<form method="POST" novalidate>
{{ form.hidden_tag() }}
<div class="row">
<div class="col-md-6">{{ render_field(form.first_name) }}</div>
<div class="col-md-6">{{ render_field(form.last_name) }}</div>
</div>
{{ render_field(form.username) }}
{{ render_field(form.email) }}
{{ render_field(form.password) }}
{{ render_field(form.confirm_password) }}
{{ render_field(form.country) }}
{{ render_field(form.agree_terms) }}
{{ form.submit(class="btn btn-primary btn-lg w-100") }}
</form>
<p class="mt-3 text-center">
Already have an account? <a href="{{ url_for('login') }}">Log in</a>
</p>
</div>
</div>
{% endblock %}
# forms.py
class ContactForm(FlaskForm):
name = StringField('Your Name', validators=[DataRequired(), Length(max=100)])
email = StringField('Your Email', validators=[DataRequired(), Email()])
subject = SelectField('Subject', choices=[
('general', 'General Inquiry'),
('support', 'Technical Support'),
('billing', 'Billing Question'),
('feedback', 'Feedback')
])
message = TextAreaField('Message', validators=[
DataRequired(),
Length(min=10, max=2000, message='Message must be 10-2000 characters.')
])
submit = SubmitField('Send Message')
# routes.py
from flask_mail import Mail, Message as MailMessage
mail = Mail(app)
@app.route('/contact', methods=['GET', 'POST'])
def contact():
form = ContactForm()
if form.validate_on_submit():
# Send email notification
msg = MailMessage(
subject=f"[Contact Form] {form.subject.data}: from {form.name.data}",
sender=app.config['MAIL_DEFAULT_SENDER'],
recipients=[app.config['ADMIN_EMAIL']],
reply_to=form.email.data
)
msg.body = f"""Name: {form.name.data}
Email: {form.email.data}
Subject: {form.subject.data}
{form.message.data}"""
try:
mail.send(msg)
flash('Message sent! We will get back to you soon.', 'success')
except Exception as e:
app.logger.error(f'Email send failed: {e}')
flash('Failed to send message. Please try again later.', 'danger')
return redirect(url_for('contact'))
return render_template('contact.html', form=form)
# forms.py
from flask_wtf.file import FileField, FileAllowed
class ProfileForm(FlaskForm):
first_name = StringField('First Name', validators=[DataRequired(), Length(max=50)])
last_name = StringField('Last Name', validators=[DataRequired(), Length(max=50)])
bio = TextAreaField('Bio', validators=[Length(max=500)])
avatar = FileField('Profile Picture', validators=[
FileAllowed(['jpg', 'jpeg', 'png'], 'Images only.')
])
submit = SubmitField('Save Changes')
# routes.py
from flask_login import login_required, current_user
@app.route('/profile/edit', methods=['GET', 'POST'])
@login_required
def edit_profile():
form = ProfileForm(obj=current_user) # Pre-populate from user object
if form.validate_on_submit():
current_user.first_name = form.first_name.data
current_user.last_name = form.last_name.data
current_user.bio = form.bio.data
if form.avatar.data:
# Delete old avatar if it exists
if current_user.avatar_filename:
old_path = os.path.join(
app.config['UPLOAD_FOLDER'], 'avatars', current_user.avatar_filename
)
if os.path.exists(old_path):
os.remove(old_path)
current_user.avatar_filename = save_file(
form.avatar.data, subfolder='avatars'
)
db.session.commit()
flash('Profile updated.', 'success')
return redirect(url_for('edit_profile'))
return render_template('edit_profile.html', form=form)
<!-- templates/edit_profile.html -->
{% from "macros/forms.html" import render_field %}
{% extends "base.html" %}
{% block content %}
<h1>Edit Profile</h1>
<form method="POST" enctype="multipart/form-data" novalidate>
{{ form.hidden_tag() }}
<div class="row">
<div class="col-md-8">
{{ render_field(form.first_name) }}
{{ render_field(form.last_name) }}
{{ render_field(form.bio) }}
</div>
<div class="col-md-4 text-center">
{% if current_user.avatar_filename %}
<img src="{{ url_for('static', filename='uploads/avatars/' + current_user.avatar_filename) }}"
class="img-thumbnail mb-3" style="max-width: 200px;">
{% endif %}
{{ render_field(form.avatar) }}
</div>
</div>
{{ form.submit(class="btn btn-primary") }}
</form>
{% endblock %}
A wizard form splits a long form into multiple steps. We store intermediate data in the session and validate one step at a time.
# forms.py
class WizardStep1Form(FlaskForm):
"""Step 1: Personal Information"""
first_name = StringField('First Name', validators=[DataRequired()])
last_name = StringField('Last Name', validators=[DataRequired()])
email = StringField('Email', validators=[DataRequired(), Email()])
next_step = SubmitField('Next')
class WizardStep2Form(FlaskForm):
"""Step 2: Address"""
street = StringField('Street Address', validators=[DataRequired()])
city = StringField('City', validators=[DataRequired()])
state = StringField('State', validators=[DataRequired()])
zip_code = StringField('ZIP Code', validators=[DataRequired()])
prev_step = SubmitField('Back')
next_step = SubmitField('Next')
class WizardStep3Form(FlaskForm):
"""Step 3: Preferences"""
plan = SelectField('Plan', choices=[
('free', 'Free'), ('pro', 'Pro ($9/mo)'), ('enterprise', 'Enterprise ($29/mo)')
])
notifications = BooleanField('Receive email notifications', default=True)
prev_step = SubmitField('Back')
finish = SubmitField('Complete Registration')
# routes.py
from flask import session
WIZARD_FORMS = {
1: WizardStep1Form,
2: WizardStep2Form,
3: WizardStep3Form
}
@app.route('/wizard', methods=['GET'])
def wizard_start():
session.pop('wizard_data', None)
return redirect(url_for('wizard_step', step=1))
@app.route('/wizard/step/<int:step>', methods=['GET', 'POST'])
def wizard_step(step):
if step not in WIZARD_FORMS:
return redirect(url_for('wizard_start'))
FormClass = WIZARD_FORMS[step]
wizard_data = session.get('wizard_data', {})
# Pre-populate from session if returning to a step
step_data = wizard_data.get(str(step), {})
form = FormClass(data=step_data) if request.method == 'GET' and step_data else FormClass()
if request.method == 'POST':
# Handle "Back" button — no validation needed
if hasattr(form, 'prev_step') and form.prev_step.data:
return redirect(url_for('wizard_step', step=step - 1))
if form.validate_on_submit():
# Save step data to session
wizard_data[str(step)] = {
field.name: field.data
for field in form
if field.name not in ('csrf_token', 'next_step', 'prev_step', 'finish')
}
session['wizard_data'] = wizard_data
if step == 3: # Final step
# Combine all wizard data and create the user
all_data = {}
for step_dict in wizard_data.values():
all_data.update(step_dict)
# Create user with all_data...
user = create_user_from_wizard(all_data)
session.pop('wizard_data', None)
flash('Registration complete!', 'success')
return redirect(url_for('dashboard'))
return redirect(url_for('wizard_step', step=step + 1))
return render_template(f'wizard_step{step}.html', form=form, step=step)
<!-- templates/wizard_step1.html -->
{% from "macros/forms.html" import render_field %}
{% extends "base.html" %}
{% block content %}
<h1>Registration - Step {{ step }} of 3</h1>
<!-- Progress bar -->
<div class="progress mb-4">
<div class="progress-bar" style="width: {{ (step / 3 * 100) | int }}%">
Step {{ step }} of 3
</div>
</div>
<form method="POST" novalidate>
{{ form.hidden_tag() }}
{{ render_field(form.first_name) }}
{{ render_field(form.last_name) }}
{{ render_field(form.email) }}
{{ form.next_step(class="btn btn-primary") }}
</form>
{% endblock %}
These are the mistakes I see most often in code reviews. Avoid them.
<!-- WRONG: form will silently fail validation -->
<form method="POST">
{{ form.username() }}
<button type="submit">Submit</button>
</form>
<!-- RIGHT: always include hidden_tag() -->
<form method="POST">
{{ form.hidden_tag() }}
{{ form.username() }}
<button type="submit">Submit</button>
</form>
Symptom: form.validate_on_submit() returns False but form.errors shows {'csrf_token': ['The CSRF token is missing.']}.
# WRONG: Trusting client-side validation
@app.route('/submit', methods=['POST'])
def submit():
# Directly using request.form without any validation
name = request.form['name'] # Can be empty, malicious, or missing entirely
db.execute(f"INSERT INTO users (name) VALUES ('{name}')")
# RIGHT: Always validate server-side
@app.route('/submit', methods=['POST'])
def submit():
form = MyForm()
if form.validate_on_submit():
# Data has been validated and is safe to use
user = User(name=form.name.data)
db.session.add(user)
db.session.commit()
HTML5 required and pattern attributes are convenience features, not security measures. A user can bypass them with browser devtools or by sending a raw HTTP request.
# WRONG: Using the original filename directly
file.save(os.path.join(upload_dir, file.filename))
# Attacker uploads: "../../../etc/passwd" or "shell.php"
# RIGHT: Always sanitize and rename
from werkzeug.utils import secure_filename
import uuid
original = secure_filename(file.filename) # Strips path components
ext = original.rsplit('.', 1)[-1].lower()
new_name = f"{uuid.uuid4().hex}.{ext}"
file.save(os.path.join(upload_dir, new_name))
# WRONG: validate_on_submit() runs before choices are set
@app.route('/assign', methods=['GET', 'POST'])
def assign():
form = AssignForm()
if form.validate_on_submit(): # Always fails — choices is empty!
pass
form.user.choices = [(u.id, u.name) for u in User.query.all()]
return render_template('assign.html', form=form)
# RIGHT: Set choices BEFORE validation
@app.route('/assign', methods=['GET', 'POST'])
def assign():
form = AssignForm()
form.user.choices = [(u.id, u.name) for u in User.query.all()]
if form.validate_on_submit():
pass
return render_template('assign.html', form=form)
# WRONG: FlaskForm adds its own CSRF token — nested forms will have duplicate tokens
class AddressForm(FlaskForm): # <-- Wrong base class
street = StringField('Street')
# RIGHT: Use wtforms.Form for sub-forms
from wtforms import Form
class AddressForm(Form): # <-- Correct
street = StringField('Street')
<!-- WRONG: files will not be sent -->
<form method="POST">
{{ form.hidden_tag() }}
{{ form.avatar() }}
<button type="submit">Upload</button>
</form>
<!-- RIGHT: enctype is required for file uploads -->
<form method="POST" enctype="multipart/form-data">
{{ form.hidden_tag() }}
{{ form.avatar() }}
<button type="submit">Upload</button>
</form>
Client-side validation (HTML5 attributes, JavaScript) improves UX. Server-side validation is the actual security boundary. Never skip it.
Even for a simple search bar, the discipline of defining a form class pays off. You get CSRF protection, consistent validation, and clear separation between form definition and route logic.
myapp/
__init__.py
forms/
__init__.py
auth.py # LoginForm, RegistrationForm
profile.py # ProfileForm, AvatarForm
admin.py # AdminSettingsForm
routes/
auth.py
profile.py
templates/
models.py
Define form rendering macros once and import them everywhere. This ensures consistent styling and error display across your entire application.
Always configure a maximum upload size. Without it, a user can send a multi-gigabyte request and crash your server:
app.config['MAX_CONTENT_LENGTH'] = 16 * 1024 * 1024 # 16 MB
Initialize CSRFProtect globally and only exempt endpoints that genuinely need it (webhooks, token-authenticated APIs):
from flask_wtf.csrf import CSRFProtect
csrf = CSRFProtect()
def create_app():
app = Flask(__name__)
csrf.init_app(app)
return app
Use the obj parameter to pre-fill a form from an existing model instance:
form = ProfileForm(obj=current_user) # GET: pre-fills from user
if form.validate_on_submit():
form.populate_obj(current_user) # POST: writes validated data back
db.session.commit()
Always use categories (success, danger, warning, info) so your template can style them appropriately with Bootstrap alert classes.
{{ form.hidden_tag() }} in your templates. For AJAX, send the token via the X-CSRFToken header.DataRequired then Length then Email. Write custom validators for business rules using validate_<fieldname> methods or standalone functions.enctype="multipart/form-data" on the form, FileAllowed/FileRequired validators, and secure_filename + UUID renaming before saving.SelectField choices from the database before calling validate_on_submit(), use FieldList for repeating fields, and FormField for nested structures.MAX_CONTENT_LENGTH to prevent denial-of-service via oversized uploads.