Flask-Suspense

Display loaders without requiring AJAX. Use streaming templates to delay the rendering of parts of the template to the end of the response.

This is similar to React's Suspense and Next.js data loading mechanism.

Installation

pip install flask-suspense

Usage

Enable the Suspense extension. Decorate your long running data loader using @defer and pass it to the template. Render the template using flask_suspense.render_template.

from flask import Flask
from flask_suspense import Suspense, defer, render_template

app = Flask(__name__)
Suspense(app)

@app.route('/')
def index():

    @defer
    def data():
        time.sleep(2)  # Simulate a long-running process
        return "Loaded data"
    
    return render_template('index.html', data=data)

In your template, use the {% suspense %} block to defer rendering to the end of the template.

{% suspense %}
    {{ data }}
{% endsuspense %}

You can also display a loading message:

{% suspense %}
    {{ data }}
{% fallback %}
    <p>Loading...</p>
{% endsuspense %}

Tip

The {% suspense %} block does not require the use of @defer loaders. It will simply delay the rendering of its content to the end of the template.

Warning

Using Flask.render_template() will not render the suspense blocks

You can disable suspense by passing _suspense_disabled=True to render_template().

Tip

flask_suspense.stream_template() is also available

Usage with Content Securiy Policy (CSP)

Using suspense blocks will use inline script tags. This may conflict with your content security policy.

A nonce can be provided to ensure the script tag is allowed. Set the nonce via g.suspense_nonce.

@app.before_request
def setup_nonce():
    g.suspense_nonce = "random string"

@app.after_request
def setup_csp(resp):
    resp.headers['Content-Security-Policy'] = f"script-src 'nonce-{g.suspense_once}';"
    return resp

About the loader

A loading div will be inserted in place of your suspense block. This div has a suspense-loader class. It will be replaced once the content is loaded.

How does it work ?

Streaming responses allow to start sending back to the response in multiple parts.

When rendering, {% suspense %} blocks are converted to macros and replaced by a loading div at the location they have been used.

The template is rendered in full first, without calling the suspense macros. It is sent back to the client.

Suspense macros are then called and their results are sent back wrapped in script tags that replace the loaders.

@defer loaders ensures that the data loading will only start when the object is called as part of the macro, at the end of the stream.

Customizing how content is inserted

When a suspense block is sent to the client, it replaces the loader using a simple document.getElementById(suspenseId).outerHTML = suspenseBlockHtml.

This can be customized by providing a custom function window.__replace_suspense__ on the frontend.

<script>
    window.__replace_suspense__ = (id, html) => {
        console.log(`Received suspense block ${id}`)
        document.getElementById(id).outerHTML = html;
    };
</script>