Flash Messages#

New in version 2.7.0.

Flash messages are a powerful tool for conveying information to the user, such as success notifications, warnings, or errors through one-time messages alongside a response due to some kind of user action.

They are typically used to display a message on the next page load and are a great way to enhance user experience by providing immediate feedback on their actions from things like form submissions.

Registering the plugin#

The FlashPlugin can be easily integrated with different templating engines. Below are examples of how to register the FlashPlugin with Jinja2, Mako, and MiniJinja templating engines.

Registering the flash message plugin using the Jinja2 templating engine#
from litestar import Litestar
from litestar.contrib.jinja import JinjaTemplateEngine
from litestar.middleware.session.server_side import ServerSideSessionConfig
from litestar.plugins.flash import FlashConfig, FlashPlugin
from litestar.template.config import TemplateConfig

template_config = TemplateConfig(engine=JinjaTemplateEngine, directory="templates")
flash_plugin = FlashPlugin(config=FlashConfig(template_config=template_config))

app = Litestar(
    plugins=[flash_plugin],
    middleware=[ServerSideSessionConfig().middleware],
)
Registering the flash message plugin using the Mako templating engine#
from litestar import Litestar
from litestar.contrib.mako import MakoTemplateEngine
from litestar.middleware.session.server_side import ServerSideSessionConfig
from litestar.plugins.flash import FlashConfig, FlashPlugin
from litestar.template.config import TemplateConfig

template_config = TemplateConfig(engine=MakoTemplateEngine, directory="templates")
flash_plugin = FlashPlugin(config=FlashConfig(template_config=template_config))

app = Litestar(
    plugins=[flash_plugin],
    middleware=[ServerSideSessionConfig().middleware],
)
Registering the flash message plugin using the MiniJinja templating engine#
from litestar import Litestar
from litestar.contrib.minijinja import MiniJinjaTemplateEngine
from litestar.middleware.session.server_side import ServerSideSessionConfig
from litestar.plugins.flash import FlashConfig, FlashPlugin
from litestar.template.config import TemplateConfig

template_config = TemplateConfig(engine=MiniJinjaTemplateEngine, directory="templates")
flash_plugin = FlashPlugin(config=FlashConfig(template_config=template_config))

app = Litestar(
    plugins=[flash_plugin],
    middleware=[ServerSideSessionConfig().middleware],
)

Using the plugin#

After registering the FlashPlugin with your application, you can start using it to add and display flash messages within your application routes.

Here is an example showing how to use the FlashPlugin with the Jinja2 templating engine to display flash messages. The same approach applies to Mako and MiniJinja engines as well.

Using the flash message plugin with Jinja2 templating engine to display flash messages#
from litestar import Litestar, Request, get
from litestar.contrib.jinja import JinjaTemplateEngine
from litestar.middleware.session.server_side import ServerSideSessionConfig
from litestar.plugins.flash import FlashConfig, FlashPlugin, flash
from litestar.response import Template
from litestar.template.config import TemplateConfig

template_config = TemplateConfig(engine=JinjaTemplateEngine, directory="templates")
flash_plugin = FlashPlugin(config=FlashConfig(template_config=template_config))


@get()
async def index(request: Request) -> Template:
    """Example of adding and displaying a flash message."""
    flash(request, "Oh no! I've been flashed!", category="error")

    return Template(
        template_str="""
    <h1>Flash Message Example</h1>
    {% for message in get_flashes() %}
    <p>{{ message.message }} (Category:{{ message.category }})</p>
    {% endfor %}
    """
    )


app = Litestar(
    plugins=[flash_plugin],
    route_handlers=[index],
    template_config=template_config,
    middleware=[ServerSideSessionConfig().middleware],
)

Breakdown#

  1. Here we import the requires classes and functions from the Litestar package and related plugins.

  2. Flash messages requires a valid session configuration, so we create and enable the ServerSideSession middleware.

  3. We then create our TemplateConfig and FlashConfig instances, each setting up the configuration for the template engine and flash messages, respectively.

  4. A single route handler named index is defined using the @get() decorator.

    • Within this handler, the flash function is called to add a new flash message. This message is stored in the request’s context, making it accessible to the template engine for rendering in the response.

    • The function returns a Template instance, where template_str (read more about template strings) contains inline HTML and Jinja2 template code. This template dynamically displays any flash messages by iterating over them with a Jinja2 for loop. Each message is wrapped in a paragraph (<p>) tag, showing the message content and its category.

  5. Finally, a Litestar application instance is created, specifying the flash_plugin and index route handler in its configuration. The application is also configured with the template_config, which includes the Jinja2 templating engine and the path to the templates directory.