Custom Filters

When built-in filters aren’t enough, you can create custom ones.

Register a custom filter

python

from flask import Flask
 
app = Flask(__name__)
 
 
def format_username(value: str) -> str:
    return value.strip().title()
 
 
app.jinja_env.filters["format_username"] = format_username

Use it in templates:

html

<p>{{ username | format_username }}</p>

Alternative: decorator style

Flask also supports:

python

@app.template_filter("format_username")
def format_username(value):
    return value.strip().title()

When to use custom filters

• formatting dates
• truncating text in a consistent way
• normalizing usernames/display names

If the same template logic repeats, it’s a good candidate for a filter.

A filter is a function with a name in the template namespace

filters.py

@app.template_filter("shout")
def shout(s):
    return str(s).upper() + "!"

usage

{{ 'hi'|shout }}      ->  HI!

The value on the left of | becomes the first argument. Extra arguments come from the call: {{ x|round(2) }} invokes round(x, 2). Filters chain left to right, so {{ v|upper|replace('A','@') }} uppercases first and then replaces — measured '@BC' for v = 'abc'.

diagram Diagram mermaid

  flowchart LR
  V["value"] --> F1["|upper"] --> F2["|replace('A','@')"] --> O["output, then escaped"]

The part that goes wrong: filters that return HTML

A filter’s return value is escaped like any other value. A filter that builds markup therefore comes out as visible text:

badge.py

@app.template_filter("badge_unsafe")
def badge_unsafe(s):
    return f"<span class='b'>{s}</span>"        # a plain str

measured

{{ 'ok'|badge_unsafe }}       ->  <span class='b'>ok</span>

The obvious fix is |safe, and it is the wrong one:

measured, with hostile input

{{ v|badge_unsafe|safe }}  where v = <script>x</script>
->  <span class='b'><script>x</script></span>        <- the script runs

|safe disables escaping for the whole result, including the interpolated user value. The correct approach marks only the wrapper as safe and lets the value be escaped:

badge_safe.py

from markupsafe import Markup
 
@app.template_filter("badge_safe")
def badge_safe(s):
    return Markup("<span class='b'>{}</span>").format(s)

measured, same hostile input

{{ v|badge_safe }}
->  <span class='b'>&lt;script&gt;x&lt;/script&gt;</span>     <- markup kept, input escaped

Markup.format escapes every argument as it substitutes. That single difference is what separates a safe HTML-producing filter from an injection point.

Never write |safe after a filter that touches request data

If you find yourself appending |safe, the filter should have returned Markup instead. |safe is for values you produced entirely yourself and can vouch for.

Built-ins worth knowing before writing your own

filter	measured
{{ v|default('none') }} when v is missing	none
{{ [1,2,3]|length }}	3
{{ ['a','b']|join('-') }}	a-b
{{ 3.14159|round(2) }}	3.14
{{ {'a':1}|tojson }}	{"a": 1}

tojson is the safe way to hand data to JavaScript — it escapes characters that would otherwise break out of a <script> block.

See it move

sketch A filter's output is escaped too p5.js Pause Restart

Returning a plain string gets escaped; adding |safe unescapes the user input as well; returning Markup escapes only the value.

Check yourself

pch.quizTag pch.quizDefaultTitle

1. A filter returns the plain string '<span>ok</span>'. What appears on the page?

   A a rendered span element B the escaped text &lt;span&gt;ok&lt;/span&gt;, visible to the reader C nothing, the markup is stripped D a Jinja2 error
   pch.quizShowAnswer

   B — the escaped text &lt;span&gt;ok&lt;/span&gt;, visible to the reader — A filter's return value is escaped like any other value. To emit real markup the filter must return Markup, not a str.

2. Why is {{ v|badge_unsafe|safe }} dangerous when v comes from a request?

   A safe is slower than escaping B |safe disables escaping for the whole result, including the interpolated user value, so a script tag in v executes C the filter runs twice D safe only works on strings shorter than 255 characters
   pch.quizShowAnswer

   B — |safe disables escaping for the whole result, including the interpolated user value, so a script tag in v executes — Measured with v = <script>x</script>: the output was <span class='b'><script>x</script></span>. Return Markup(...).format(s) instead so the wrapper is markup and the value is escaped.

3. What does Markup('<span>{}</span>').format(s) do differently from an f-string?

   A nothing, they produce the same result B it escapes each substituted argument while keeping the surrounding markup as HTML C it disables autoescaping for the template D it validates that s is valid HTML
   pch.quizShowAnswer

   B — it escapes each substituted argument while keeping the surrounding markup as HTML — Markup.format escapes its arguments as it substitutes them. That is what makes the wrapper render as markup while hostile input is neutralised.