A Flask application can return plain text:
@app.route("/")
def home():
return "Welcome to Flask"
But real websites need complete HTML pages containing:
- Headings
- Navigation
- Forms
- Product lists
- User profiles
- Images
- Buttons
- Dynamic database data
- Conditional content
- Reusable layouts
Writing all that HTML directly inside Python would quickly become difficult to maintain.
Flask solves this problem using templates.
Flask uses the Jinja template engine to generate dynamic HTML pages from Python data.
For example, instead of writing:
<h1>Welcome Ankit</h1>
for every user, you can create:
<h1>Welcome {{ username }}</h1>
and Flask can provide a different username for every request.
This guide explains how Flask templates and Jinja work, from creating your first template to building reusable layouts, loops, conditions, filters, macros, forms, and dynamic pages.
What Is a Flask Template?
A Flask template is usually an HTML file that can contain both normal HTML and Jinja template expressions.
For example:
<!DOCTYPE html>
<html>
<head>
<title>{{ page_title }}</title>
</head>
<body>
<h1>Hello {{ username }}</h1>
</body>
</html>
The HTML defines the page structure.
Jinja inserts dynamic values.
If Flask provides:
page_title = "Dashboard"
username = "Alex"
the generated HTML becomes conceptually:
<!DOCTYPE html>
<html>
<head>
<title>Dashboard</title>
</head>
<body>
<h1>Hello Alex</h1>
</body>
</html>
The browser receives normal HTML.
It does not need to understand Jinja.
What Is Jinja?
Jinja is a template engine for Python.
Flask integrates Jinja so developers can combine HTML templates with dynamic server-side data.
Jinja allows templates to use features such as:
Variables
Conditions
Loops
Filters
Template inheritance
Includes
Macros
Expressions
For example:
{{ username }}
prints a value.
{% if logged_in %}
runs conditional template logic.
{% for product in products %}
loops through data.
This makes HTML pages dynamic without placing large amounts of HTML inside Python files.
How Flask Templates Work
The basic request flow looks like this:
Browser
↓
GET /profile
↓
Flask Route
↓
Python loads data
↓
render_template()
↓
Jinja Template
↓
Dynamic HTML
↓
Browser
For example:
@app.route("/profile")
def profile():
user = {
"name": "Alex",
"role": "Developer"
}
return render_template(
"profile.html",
user=user
)
Flask passes user into the template.
Jinja uses that data to create HTML.
The templates Folder
By default, Flask commonly looks for templates inside a directory named:
templates/
A basic project might look like:
flask_app/
│
├── app.py
│
├── templates/
│ ├── index.html
│ ├── about.html
│ └── profile.html
│
└── static/
├── css/
├── js/
└── images/
Keeping templates separate from Python code makes the project easier to understand.
Your First Flask Template
Create:
templates/index.html
Add:
<!DOCTYPE html>
<html>
<head>
<title>My Flask App</title>
</head>
<body>
<h1>Hello Flask!</h1>
<p>This page is rendered using Jinja.</p>
</body>
</html>
Now update app.py:
from flask import Flask, render_template
app = Flask(__name__)
@app.route("/")
def home():
return render_template("index.html")
Run the application:
flask --app app run --debug
Visit the local address displayed by Flask.
Flask will locate:
templates/index.html
and render it.
What Is render_template()?
render_template() is one of the most important functions when building server-rendered Flask websites.
Import it:
from flask import render_template
Then:
return render_template("index.html")
Flask loads the requested template and lets Jinja process it.
You can also pass Python values:
return render_template(
"profile.html",
username="Alex",
age=25
)
Inside the template:
<h1>{{ username }}</h1>
<p>Age: {{ age }}</p>
The values become available inside Jinja.
Jinja Variable Syntax
Jinja uses double curly braces to output values:
{{ variable }}
Example:
<h1>{{ title }}</h1>
Python:
@app.route("/")
def home():
return render_template(
"index.html",
title="Flask Tutorial"
)
Rendered result:
<h1>Flask Tutorial</h1>
Passing Multiple Variables
You can send several values to a template.
@app.route("/profile")
def profile():
return render_template(
"profile.html",
name="Emma",
profession="Developer",
experience=3
)
Template:
<h1>{{ name }}</h1>
<p>Profession: {{ profession }}</p>
<p>Experience: {{ experience }} years</p>
This is one of the most common patterns in Flask applications.
Passing a Dictionary to Jinja
Instead of sending individual values:
user = {
"name": "Emma",
"email": "emma@example.com",
"role": "Developer"
}
Pass it:
return render_template(
"profile.html",
user=user
)
Then access values:
<h1>{{ user.name }}</h1>
<p>{{ user.email }}</p>
<p>{{ user.role }}</p>
Jinja provides convenient attribute-style access for many objects and mappings.
Passing Lists to Templates
Suppose Python contains:
skills = [
"Python",
"Flask",
"SQL",
"JavaScript"
]
Pass it:
return render_template(
"skills.html",
skills=skills
)
Now the template can loop through the list.
<ul>
{% for skill in skills %}
<li>{{ skill }}</li>
{% endfor %}
</ul>
Rendered result:
Python
Flask
SQL
JavaScript
Understanding Jinja Syntax
Three syntax patterns are especially important.
Output Expressions
{{ ... }}
Used to display values.
Example:
{{ username }}
Statements
{% ... %}
Used for logic such as:
if
for
block
extends
include
macro
Example:
{% if logged_in %}
Comments
{# ... #}
Example:
{# User profile section #}
Jinja comments are processed server-side and are not intended to appear in the rendered HTML output.
Jinja if Statement
Templates often need conditional content.
Example:
{% if logged_in %}
<h2>Welcome back!</h2>
{% endif %}
Python:
return render_template(
"dashboard.html",
logged_in=True
)
The content appears only when the condition is true.
if and else
Example:
{% if logged_in %}
<a href="/dashboard">
Dashboard
</a>
{% else %}
<a href="/login">
Login
</a>
{% endif %}
This is useful for showing different UI depending on application state.
if, elif and else
Jinja also supports multiple conditions.
{% if score >= 90 %}
<p>Grade: A</p>
{% elif score >= 75 %}
<p>Grade: B</p>
{% elif score >= 60 %}
<p>Grade: C</p>
{% else %}
<p>Grade: D</p>
{% endif %}
This behaves similarly to Python conditional logic.
Checking Whether Data Exists
A common pattern is:
{% if products %}
<p>Products available.</p>
{% else %}
<p>No products found.</p>
{% endif %}
An empty list usually evaluates as false in this context.
This is useful for empty-state interfaces.
Jinja for Loop
One of the most useful Jinja features is looping.
Python:
products = [
"Laptop",
"Phone",
"Tablet"
]
Template:
<ul>
{% for product in products %}
<li>{{ product }}</li>
{% endfor %}
</ul>
Jinja repeats the HTML for every product.
Looping Through Dictionaries
Suppose:
products = [
{
"name": "Laptop",
"price": 800
},
{
"name": "Phone",
"price": 500
}
]
Pass it:
return render_template(
"products.html",
products=products
)
Template:
{% for product in products %}
<article>
<h2>{{ product.name }}</h2>
<p>
${{ product.price }}
</p>
</article>
{% endfor %}
This pattern is extremely common for:
Products
Blog posts
Users
Orders
Comments
Notifications
The loop Variable
Inside a Jinja loop, you get a special loop object.
Example:
{% for product in products %}
<p>
{{ loop.index }}.
{{ product.name }}
</p>
{% endfor %}
loop.index starts from:
1
Useful loop properties include:
loop.index
loop.index0
loop.first
loop.last
loop.length
loop.index vs loop.index0
Example:
{{ loop.index }}
starts from:
1
while:
{{ loop.index0 }}
starts from:
0
Use whichever matches your display requirements.
Checking the First or Last Item
Example:
{% for item in items %}
{% if loop.first %}
<strong>First:</strong>
{% endif %}
{{ item }}
{% endfor %}
Similarly:
{% if loop.last %}
can identify the last iteration.
Jinja for-else
Jinja supports an else block for loops.
{% for product in products %}
<p>{{ product.name }}</p>
{% else %}
<p>No products found.</p>
{% endfor %}
This is a clean way to handle empty lists.
What Are Jinja Filters?
Filters transform values before displaying them.
Syntax:
{{ value | filter }}
For example:
{{ username | upper }}
If:
username = "alex"
the output becomes:
ALEX
Common Jinja Filters
Useful filters include:
upper
lower
title
capitalize
length
default
join
replace
sort
reverse
round
Availability and behavior can depend on Jinja version and the value type, so check the relevant filter when using less common ones.
upper Filter
{{ username | upper }}
Example output:
ALEX
lower Filter
{{ category | lower }}
Example:
PYTHON
becomes:
python
title Filter
{{ article_title | title }}
Useful when formatting title-like text.
length Filter
{{ products | length }}
If the list contains 5 products:
5
is displayed.
Example:
<p>
Total Products:
{{ products | length }}
</p>
default Filter
Sometimes a value may be missing or undefined.
Example:
{{ username | default("Guest") }}
This provides a fallback for an undefined value.
Depending on your desired behavior, remember that an undefined value and a defined-but-false value are not always treated identically by default.
Chaining Filters
Filters can be chained.
{{ username | trim | upper }}
The value is processed from left to right through the filter chain.
Use chains carefully so templates remain readable.
What Is Template Inheritance?
Most websites contain repeated page elements.
For example:
HTML structure
<head>
Navigation
Footer
CSS imports
JavaScript imports
Without inheritance, every page might repeat all of this HTML.
Jinja solves this with template inheritance.
You create a base template:
base.html
Then other templates extend it.
Creating base.html
Example:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>
{% block title %}
My Flask App
{% endblock %}
</title>
</head>
<body>
<nav>
<a href="/">Home</a>
<a href="/about">About</a>
<a href="/contact">Contact</a>
</nav>
<main>
{% block content %}
{% endblock %}
</main>
<footer>
<p>My Flask App</p>
</footer>
</body>
</html>
Notice:
{% block title %}
and:
{% block content %}
These define sections child templates can replace.
Extending a Base Template
Create:
templates/index.html
Add:
{% extends "base.html" %}
{% block title %}
Home
{% endblock %}
{% block content %}
<h1>Welcome Home</h1>
<p>This is the homepage.</p>
{% endblock %}
Jinja combines:
base.html
+
index.html
to produce the final HTML.
Why Template Inheritance Matters
Suppose your website has:
Home
About
Contact
Products
Profile
Dashboard
Settings
Without inheritance, each file may repeat:
Navigation
Footer
Meta tags
CSS
JavaScript
Page wrapper
With inheritance:
base.html
↓
Shared Layout
↓
Individual Page Content
If the navigation changes, you update it once.
This significantly improves maintainability.
Multiple Jinja Blocks
A base template can define several blocks.
Example:
<title>
{% block title %}
Default Title
{% endblock %}
</title>
{% block styles %}
{% endblock %}
{% block content %}
{% endblock %}
{% block scripts %}
{% endblock %}
A child page can override only what it needs.
Example:
{% block scripts %}
<script src="..."></script>
{% endblock %}
This provides flexibility without duplicating the full page layout.
Using super()
Sometimes a child template should keep content from the parent block and add more.
You can use:
{{ super() }}
For example, if a base styles block contains shared CSS references, a child block can include the parent content and then add page-specific styles.
This is useful when extending rather than completely replacing a block.
What Is Jinja include?
Sometimes you want to reuse a smaller HTML component rather than an entire layout.
For example:
navbar.html
footer.html
alerts.html
sidebar.html
Use:
{% include "navbar.html" %}
Example structure:
templates/
│
├── base.html
│
├── index.html
│
└── components/
├── navbar.html
└── footer.html
Then:
{% include "components/navbar.html" %}
This helps keep repeated template fragments organized.
include vs extends
These concepts solve different problems.
extends
Used for template inheritance.
{% extends "base.html" %}
Think:
This page uses this layout.
include
Used to insert a reusable template fragment.
{% include "components/navbar.html" %}
Think:
Insert this component here.
What Are Jinja Macros?
A macro is similar to a reusable template function.
Suppose you repeatedly create buttons:
<a href="/edit/1" class="button">
Edit
</a>
You could define a macro.
{% macro button(text, url) %}
<a href="{{ url }}" class="button">
{{ text }}
</a>
{% endmacro %}
Then:
{{ button("Edit", "/edit/1") }}
Macros are useful for reusable template patterns.
Importing Macros
A cleaner approach is to store macros separately.
Example:
templates/
└── macros/
└── ui.html
Inside:
{% macro button(text, url) %}
<a href="{{ url }}">
{{ text }}
</a>
{% endmacro %}
Import it:
{% from "macros/ui.html" import button %}
Then:
{{ button("Dashboard", "/dashboard") }}
Macros with Multiple Parameters
Example:
{% macro input_field(
name,
label,
type="text"
) %}
<label for="{{ name }}">
{{ label }}
</label>
<input
type="{{ type }}"
id="{{ name }}"
name="{{ name }}"
>
{% endmacro %}
Use:
{{ input_field(
"email",
"Email Address",
"email"
) }}
This can reduce repeated form markup.
Using url_for() Inside Templates
Hard-coding internal URLs is usually unnecessary.
Instead of:
<a href="/about">
About
</a>
use:
<a href="{{ url_for('about') }}">
About
</a>
If the route later changes, Flask can still generate the correct URL from the endpoint.
url_for() with Dynamic Routes
Suppose:
@app.route("/users/<int:user_id>")
def profile(user_id):
...
Inside Jinja:
<a href="{{
url_for(
'profile',
user_id=user.id
)
}}">
View Profile
</a>
Flask might generate:
/users/25
This is much safer than manually concatenating URL strings.
Linking Static Files
Flask static assets are commonly served through the static endpoint.
CSS:
<link
rel="stylesheet"
href="{{
url_for(
'static',
filename='css/style.css'
)
}}"
>
JavaScript:
<script
src="{{
url_for(
'static',
filename='js/app.js'
)
}}"
></script>
Image:
<img
src="{{
url_for(
'static',
filename='images/logo.webp'
)
}}"
alt="Website Logo"
>
Avoid manually building static paths when url_for() can generate them.
Organizing Templates
As a project grows, avoid putting every HTML file directly inside templates/.
Instead of:
templates/
├── login.html
├── register.html
├── product_list.html
├── product_detail.html
├── order_list.html
├── order_detail.html
├── profile.html
└── settings.html
you can group related templates:
templates/
│
├── base.html
│
├── home/
│ └── index.html
│
├── auth/
│ ├── login.html
│ └── register.html
│
├── products/
│ ├── list.html
│ └── detail.html
│
├── orders/
│ ├── list.html
│ └── detail.html
│
└── users/
├── profile.html
└── settings.html
Then:
render_template(
"products/detail.html"
)
This becomes much easier to manage.
Templates with Flask Blueprints
Blueprint-based projects can also organize templates by feature.
Example:
app/
│
├── auth/
│ ├── routes.py
│ └── templates/
│ └── auth/
│ ├── login.html
│ └── register.html
│
└── products/
├── routes.py
└── templates/
└── products/
├── list.html
└── detail.html
Using feature-specific subdirectories helps prevent template-name collisions.
For example:
render_template(
"auth/login.html"
)
is clearer than several Blueprints each having an unrelated index.html.
Rendering Database Data
Templates frequently display database results.
Imagine a route loads products:
@app.route("/products")
def products():
products = Product.query.all()
return render_template(
"products/list.html",
products=products
)
Template:
{% for product in products %}
<article>
<h2>
{{ product.name }}
</h2>
<p>
${{ product.price }}
</p>
</article>
{% else %}
<p>No products available.</p>
{% endfor %}
The route retrieves the data.
The template presents the data.
This separation is important.
Keep Business Logic Out of Templates
Jinja supports conditions and expressions, but templates should not become your main business-logic layer.
Good template logic:
{% if user.is_authenticated %}
<p>Welcome {{ user.name }}</p>
{% endif %}
Poor conceptual design:
Calculate tax
Apply discount rules
Check inventory
Determine payment eligibility
Update database
inside a template.
Those responsibilities belong in Python application code.
A good rule is:
Prepare the data in Python and use Jinja primarily to present it.
Forms in Flask Templates
HTML forms are frequently rendered through templates.
Example:
<form
method="POST"
action="{{ url_for('login') }}"
>
<label for="email">
Email
</label>
<input
type="email"
id="email"
name="email"
required
>
<label for="password">
Password
</label>
<input
type="password"
id="password"
name="password"
required
>
<button type="submit">
Login
</button>
</form>
The form sends data to a Flask route.
Processing Template Form Data
Python:
from flask import request
@app.route(
"/login",
methods=["GET", "POST"]
)
def login():
if request.method == "POST":
email = request.form.get("email")
password = request.form.get("password")
# Validate credentials here.
return render_template(
"auth/login.html"
)
Flow:
Template Form
↓
POST /login
↓
Flask Route
↓
request.form
↓
Validation
↓
Response
For real authentication forms, also implement appropriate security measures such as CSRF protection and secure password handling.
Displaying Form Errors
Suppose Python creates:
error = "Invalid email or password"
Pass it:
return render_template(
"auth/login.html",
error=error
)
Template:
{% if error %}
<div class="error">
{{ error }}
</div>
{% endif %}
This allows server-side validation feedback to appear in the HTML page.
Preserving Form Values
If form validation fails, users usually should not need to re-enter every non-sensitive field.
Python can pass submitted data back:
return render_template(
"register.html",
name=name,
email=email,
error=error
)
Template:
<input
type="text"
name="name"
value="{{ name or '' }}"
>
Do not repopulate password fields.
Flash Messages in Templates
Flask includes a flash-message system for temporary messages.
Python:
from flask import flash
flash(
"Profile updated successfully.",
"success"
)
A template can retrieve messages:
{% with messages =
get_flashed_messages(
with_categories=true
)
%}
{% for category, message in messages %}
<div class="alert {{ category }}">
{{ message }}
</div>
{% endfor %}
{% endwith %}
Flash messages are commonly useful for:
Login success
Registration success
Validation errors
Profile updates
Deleted records
What Is Jinja Autoescaping?
Security is extremely important when displaying user-controlled data.
Imagine a user enters HTML or script-like content as a name.
If a template engine blindly inserted that text as executable HTML, it could create a cross-site scripting risk.
Jinja automatically escapes values in common HTML template contexts configured by Flask.
For example:
{{ comment }}
is normally escaped when rendered through standard HTML templates.
This helps prevent user-controlled HTML from being interpreted as active markup.
What Does Escaping Mean?
Suppose the value contains:
<script>alert("Hello")</script>
Escaping converts special HTML characters so the browser treats them as text rather than executable markup.
Conceptually:
< becomes <
> becomes >
This is an important security feature.
Be Careful with the safe Filter
Jinja provides:
{{ content | safe }}
This tells Jinja that the value should be treated as safe HTML.
Do not use safe on untrusted user input simply to make HTML display correctly.
For example:
{{ user_comment | safe }}
can be dangerous if the value contains malicious markup.
Only mark content as safe when you have a trustworthy sanitization strategy and understand exactly where the content came from.
Jinja Expressions
Jinja supports simple expressions.
For example:
{{ price * quantity }}
or:
{% if age >= 18 %}
However, complex application calculations should generally happen in Python.
Instead of calculating an entire checkout total in a template:
Subtotal
Discount
Tax
Shipping
Coupon
Final total
calculate it in your application/service layer and pass the final values to the template.
This keeps templates easier to understand and test.
Setting Variables in Jinja
Jinja allows variables to be assigned with set.
Example:
{% set page_title = "Dashboard" %}
<h1>{{ page_title }}</h1>
This can be useful for small presentation-related values.
Do not use template variables as a replacement for proper Python application state.
Jinja Tests
Jinja can test values.
For example:
{% if username is defined %}
<p>{{ username }}</p>
{% endif %}
You may also encounter tests such as:
defined
undefined
none
even
odd
Example:
{% if user is none %}
<p>User not found.</p>
{% endif %}
Tests make template conditions more expressive.
Checking User Roles
Templates may conditionally show interface elements.
Example:
{% if user.role == "admin" %}
<a href="{{ url_for('admin.dashboard') }}">
Admin Dashboard
</a>
{% endif %}
However, this is only a UI decision.
It does not secure the admin route.
Your backend must still enforce authorization.
Never treat:
{% if user.role == "admin" %}
as your actual security layer.
Template Context
Values available to a template are known as its context.
For example:
return render_template(
"profile.html",
user=user,
posts=posts,
page_title="Profile"
)
The context contains:
user
posts
page_title
Jinja can access those values while rendering the page.
Context Processors
Sometimes the same value is needed across many templates.
For example:
Current year
Application name
Global navigation data
Instead of manually passing the same value from every route, Flask supports context processors.
Example:
@app.context_processor
def inject_app_name():
return {
"app_name": "My Flask App"
}
Now templates can access:
{{ app_name }}
without every route explicitly passing it.
Use global context values carefully; too many hidden global variables can make templates harder to understand.
Creating a Reusable Navigation Menu
Suppose your base template contains:
<nav>
<a href="{{ url_for('home') }}">
Home
</a>
<a href="{{ url_for('products') }}">
Products
</a>
<a href="{{ url_for('about') }}">
About
</a>
</nav>
Because this lives in:
base.html
every page extending base.html automatically receives the navigation.
This is one of the biggest practical benefits of template inheritance.
Creating Reusable Product Cards
Instead of repeating product HTML, you can create a macro.
{% macro product_card(product) %}
<article class="product-card">
<h2>
{{ product.name }}
</h2>
<p>
${{ product.price }}
</p>
<a href="{{
url_for(
'products.detail',
product_id=product.id
)
}}">
View Product
</a>
</article>
{% endmacro %}
Then:
{% for product in products %}
{{ product_card(product) }}
{% endfor %}
This makes repeated UI easier to maintain.
Example Blog Template
Python:
@app.route("/blog")
def blog():
posts = [
{
"title": "Learn Flask",
"slug": "learn-flask"
},
{
"title": "Flask Routing Guide",
"slug": "flask-routing-guide"
}
]
return render_template(
"blog/list.html",
posts=posts
)
Template:
{% extends "base.html" %}
{% block title %}
Blog
{% endblock %}
{% block content %}
<h1>Latest Articles</h1>
{% for post in posts %}
<article>
<h2>
{{ post.title }}
</h2>
<a href="{{
url_for(
'blog_post',
slug=post.slug
)
}}">
Read Article
</a>
</article>
{% else %}
<p>No articles available.</p>
{% endfor %}
{% endblock %}
This demonstrates:
Template inheritance
Dynamic values
Loops
url_for()
Empty states
in one practical example.
Example User Profile Template
Python:
@app.route("/profile")
def profile():
user = {
"name": "Alex",
"email": "alex@example.com",
"skills": [
"Python",
"Flask",
"SQL"
]
}
return render_template(
"users/profile.html",
user=user
)
Template:
{% extends "base.html" %}
{% block title %}
{{ user.name }} - Profile
{% endblock %}
{% block content %}
<h1>{{ user.name }}</h1>
<p>{{ user.email }}</p>
<h2>Skills</h2>
<ul>
{% for skill in user.skills %}
<li>{{ skill }}</li>
{% else %}
<li>No skills added.</li>
{% endfor %}
</ul>
{% endblock %}
Example Product Listing Template
Python:
@app.route("/products")
def products():
products = [
{
"id": 1,
"name": "Laptop",
"price": 899
},
{
"id": 2,
"name": "Phone",
"price": 599
}
]
return render_template(
"products/list.html",
products=products
)
Template:
{% extends "base.html" %}
{% block content %}
<h1>Products</h1>
<div class="product-grid">
{% for product in products %}
<article>
<h2>
{{ product.name }}
</h2>
<p>
${{ product.price }}
</p>
<a href="{{
url_for(
'product_detail',
product_id=product.id
)
}}">
View Details
</a>
</article>
{% else %}
<p>No products available.</p>
{% endfor %}
</div>
{% endblock %}
This is close to how real server-rendered applications use templates.
Jinja and JavaScript
Jinja executes on the server before HTML reaches the browser.
JavaScript normally executes later in the browser.
For example:
<script>
const username = {{ username | tojson }};
</script>
Using appropriate JSON serialization is safer than manually building JavaScript strings.
Conceptually:
Flask
↓
Jinja executes
↓
HTML + JavaScript generated
↓
Browser receives response
↓
JavaScript executes
Jinja and JavaScript run at different stages.
Jinja tojson Filter
When passing Python data into JavaScript, use proper JSON serialization.
Example:
user = {
"name": "Alex",
"role": "developer"
}
Template:
<script>
const user = {{ user | tojson }};
console.log(user.name);
</script>
This is generally better than manually constructing JavaScript objects with template interpolation.
Jinja vs JavaScript Template Literals
Do not confuse:
{{ username }}
with JavaScript:
`${username}`
Jinja runs:
Server-side
JavaScript template literals run:
Client-side
This distinction is essential when debugging dynamic Flask pages.
Jinja Template Security
When working with templates:
- Keep autoescaping enabled.
- Do not mark untrusted input as
safe. - Validate user input on the backend.
- Protect forms against CSRF where appropriate.
- Do not expose secrets to templates.
- Do not rely on hidden UI for authorization.
- Escape or safely serialize data passed to JavaScript.
- Avoid exposing sensitive model properties unnecessarily.
Remember:
Anything rendered into HTML may ultimately be visible to the client.
Never send secret values to a template expecting them to remain hidden.
Templates Should Not Contain Secrets
Never render values such as:
Database password
API secret
Private authentication key
Payment secret key
Server credentials
into HTML.
Even if CSS hides an element:
<div style="display:none">
the value still exists in the page source.
Server secrets must remain on the server.
Common Flask Template Errors
TemplateNotFound
You may see:
TemplateNotFound
when Flask cannot find a template.
Check:
Folder name
Filename
Template path
Capitalization
Project structure
For example:
render_template(
"products/list.html"
)
requires the corresponding template path to exist in the configured template search locations.
Undefined Variables
Suppose the template uses:
{{ username }}
but Python does not provide the expected value.
This can produce empty or undefined behavior depending on Jinja configuration and how the variable is used.
Check that your route passes:
render_template(
"profile.html",
username=username
)
and that variable names match.
Incorrect Block Names
Base:
{% block content %}
{% endblock %}
Child:
{% block contents %}
These are different block names.
The child must override the correct block:
{% block content %}
Incorrect Template Path
If your file is:
templates/auth/login.html
use:
render_template(
"auth/login.html"
)
not simply:
render_template(
"login.html"
)
unless that file actually exists at the template root.
Common Beginner Mistakes
1. Writing Large HTML Strings in Python
Avoid:
return """
<html>
...
</html>
"""
for real pages.
Use templates.
2. Repeating Headers and Footers
Use template inheritance.
3. Hard-Coding Internal URLs
Use url_for().
4. Putting Business Logic in Jinja
Calculate important business values in Python.
5. Using safe on User Input
This can introduce security vulnerabilities.
6. Mixing Every Template into One Folder
Group templates by feature as the project grows.
7. Forgetting Empty States
Handle empty lists using conditions or for-else.
8. Treating Hidden Buttons as Authorization
Backend routes must enforce permissions.
9. Manually Creating JavaScript Data Strings
Use proper JSON serialization such as tojson where appropriate.
10. Passing Entire Objects Without Considering Exposure
Only expose the data your template actually needs.
Flask Template Best Practices
Use these practical rules:
- Keep Python logic in Python.
- Keep presentation logic in templates.
- Use
base.htmlfor shared layouts. - Use
extendsfor page inheritance. - Use
includefor reusable fragments. - Use macros for repeated template components.
- Use
url_for()for internal URLs. - Organize templates by feature.
- Keep autoescaping enabled.
- Avoid
safefor untrusted data. - Use
tojsonwhen sending structured data to JavaScript. - Create useful empty states.
- Keep template variables clearly named.
- Avoid exposing unnecessary model fields.
- Keep secrets out of rendered HTML.
Recommended Flask Template Structure
A growing project might use:
app/
│
├── templates/
│ ├── base.html
│ │
│ ├── components/
│ │ ├── navbar.html
│ │ ├── footer.html
│ │ └── alerts.html
│ │
│ ├── macros/
│ │ ├── forms.html
│ │ └── ui.html
│ │
│ ├── auth/
│ │ ├── login.html
│ │ └── register.html
│ │
│ ├── products/
│ │ ├── list.html
│ │ └── detail.html
│ │
│ └── users/
│ ├── profile.html
│ └── settings.html
│
└── static/
├── css/
├── js/
└── images/
This provides clear separation between:
Layouts
Components
Macros
Feature pages
Static assets
without creating unnecessary complexity.
Flask + Jinja Quick Cheat Sheet
Render Template
render_template(
"index.html"
)
Pass Variable
render_template(
"index.html",
username="Alex"
)
Display Variable
{{ username }}
Condition
{% if logged_in %}
...
{% endif %}
If/Else
{% if logged_in %}
...
{% else %}
...
{% endif %}
Loop
{% for item in items %}
{{ item }}
{% endfor %}
Empty Loop
{% for item in items %}
{{ item }}
{% else %}
No items
{% endfor %}
Filter
{{ username | upper }}
Extend Template
{% extends "base.html" %}
Define Block
{% block content %}
{% endblock %}
Include Template
{% include "components/navbar.html" %}
Generate URL
{{ url_for("home") }}
Static File
{{
url_for(
"static",
filename="css/style.css"
)
}}
Comment
{# Comment #}
Set Variable
{% set title = "Home" %}
JSON for JavaScript
{{ data | tojson }}
Frequently Asked Questions
What are templates in Flask?
Templates are files, usually HTML files, that Flask renders with dynamic server-side data using Jinja.
What is Jinja in Flask?
Jinja is the template engine integrated with Flask. It provides variables, loops, conditions, filters, inheritance, macros, and other template features.
Where should Flask templates be stored?
By convention, Flask applications commonly store them in:
templates/
unless the application or Blueprint uses custom template configuration.
What does render_template() do?
It loads a template, provides its context, lets Jinja render it, and returns the generated content as part of the HTTP response.
How do I display a Python variable in HTML?
Pass it through render_template():
render_template(
"index.html",
name="Alex"
)
Then:
{{ name }}
How do I create loops in Jinja?
Use:
{% for item in items %}
{{ item }}
{% endfor %}
How do I use conditions?
Use:
{% if condition %}
...
{% endif %}
What is base.html?
base.html is a common name for a shared parent layout containing repeated page elements such as navigation, footer, CSS imports, and content blocks.
What is the difference between extends and include?
extends creates template inheritance.
include inserts another template fragment at a specific location.
What are Jinja macros?
Macros are reusable template functions that can generate repeated HTML components.
Is Jinja secure?
Jinja provides important protections such as HTML autoescaping in standard Flask HTML template usage, but developers must still follow secure practices.
Using safe incorrectly, exposing secrets, or trusting unvalidated user input can still create vulnerabilities.
Can Jinja access database data?
Jinja can display database objects passed to it by Flask.
Database queries should normally happen in Python rather than directly in templates.
Can Jinja replace JavaScript?
No.
Jinja renders content on the server before the response reaches the browser.
JavaScript executes in the browser and handles client-side interaction.
They solve different problems.
Flask Templates Learning Roadmap
A good learning sequence is:
render_template()
↓
Variables
↓
Conditions
↓
Loops
↓
Filters
↓
url_for()
↓
Template Inheritance
↓
Includes
↓
Macros
↓
Forms
↓
Flash Messages
↓
Template Security
↓
Reusable Components
↓
Blueprint Template Organization
Start by becoming comfortable with:
{{ variable }}
then:
{% if %}
and:
{% for %}
After that, learn inheritance.
Template inheritance is one of the most useful Jinja features for real Flask websites.
Final Thoughts
Flask templates allow you to keep Python application logic separate from HTML presentation.
Instead of generating pages inside Python:
return "<h1>Hello Alex</h1>"
you can write reusable templates:
<h1>Hello {{ username }}</h1>
and provide the data from Flask:
return render_template(
"profile.html",
username="Alex"
)
As applications grow, Jinja provides more powerful tools:
Variables
Conditions
Loops
Filters
Template inheritance
Includes
Macros
URL generation
Reusable components
A well-organized Flask website might eventually use:
templates/
├── base.html
├── components/
├── macros/
├── auth/
├── products/
└── users/
The most important principle is simple:
Python should prepare the data and handle application logic.
Jinja should focus primarily on presenting that data as HTML.
Once you understand render_template(), variables, loops, conditions, url_for(), and template inheritance, you have the core Jinja skills needed to build dynamic server-rendered Flask websites.
