---
title: "Flash messages API"
manual: "TYPO3 Explained"
version: "13.4"
permalink: "https://docs.typo3.org/permalink/t3coreapi:flash-messages-api@13.4"
source: "ApiOverview/FlashMessages/FlashMessagesApi.rst"
rendered: "2026-09-21T07:21:01+00:00"
---

# Flash messages API {#flash-messages-api}

## Instantiate a flash message {#flash-messages-api-instantiate-flash-message}

Creating a flash message is achieved by instantiating an object
of class `\TYPO3\CMS\Core\Messaging\FlashMessage`:

**EXT:some_extension/Classes/Controller/SomeController.php**

```php
use TYPO3\CMS\Core\Messaging\FlashMessage;
use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Core\Type\ContextualFeedbackSeverity;

// FlashMessage($message, $title = '', $severity = ContextualFeedbackSeverity::OK, $storeInSession = false)
$message = GeneralUtility::makeInstance(FlashMessage::class,
   'My message text',
   'Message Header',
   ContextualFeedbackSeverity::WARNING,
   true
);
```

-   **`$message`**

    The text of the message

-   **`$title`**

    \[optional\] the header

-   **`$severity`**

    \[optional\] the severity (default: `ContextualFeedbackSeverity::OK`)

-   **`$storeInSession`**

    \[optional\] `true`: store in the session or `false`: store
    only in the `\TYPO3\CMS\Core\Messaging\FlashMessageQueue` object. Storage
    in the session should be used if you need the message to be still present after
    a redirection (default: `false`).

## Flash messages severities {#flash-messages-api-flash-messages-severities}

<!-- TODO: no Markdown rendering for "versionchanged" -->

The previous class constants of \TYPO3\CMS\Core\Messaging\FlashMessage
have been removed with TYPO3 v13.0.

The severity is defined by using the
`\TYPO3\CMS\Core\Type\ContextualFeedbackSeverity` enumeration:

-   `ContextualFeedbackSeverity::NOTICE` for notifications
-   `ContextualFeedbackSeverity::INFO` for information messages
-   `ContextualFeedbackSeverity::OK` for success messages
-   `ContextualFeedbackSeverity::WARNING` for warnings
-   `ContextualFeedbackSeverity::ERROR` for errors

## Add a flash message to the queue {#flash-messages-api-add-flash-message}

In backend modules you can then make that message appear on top of the
module after a page refresh or the rendering of the next page request
or render it on your own where ever you want.

In this example the `FlashMessageService` (`\TYPO3\CMS\Core\Messaging\FlashMessageService`)
is used to add a flash message at the bottom right of a module:

**EXT:my_extension/Classes/Controller/SomeController.php**

```php
use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Core\Messaging\FlashMessageService;

$flashMessageService = GeneralUtility::makeInstance(FlashMessageService::class);
$messageQueue = $flashMessageService->getMessageQueueByIdentifier();
$messageQueue->addMessage($message);
```

The message is added to the queue and then the template class calls
`\TYPO3\CMS\Core\Messaging\FlashMessageQueue::renderFlashMessages()` which renders all
messages from the queue as inline flash messages. Here's how such a message looks like in a module:

![](../../Images/ManualScreenshots/Examples/FlashMessages/FlashMessagesExample.png)

This shows flash messages with 2 types of rendering mechanisms:

-   several flash messages are displayed **inline**
-   and an additional flash message ("Record count") is rendered as top-right
    **notification** (which automatically disappear after a short delay).

<!-- TODO: no Markdown rendering for "versionadded" -->

FlashMessageQueue::NOTIFICATION_QUEUE has been added in TYPO3 v12 to
provide a simple mechanism to add flash messages (from PHP code) to be
displayed as notifications on the top-right edge of the backend. Previously,
this had to be implemented in JavaScript (e.g. Notification.success()),
which is also still possible, see JavaScript-based flash messages (Notification API).

Use the `FlashMessageQueue::NOTIFICATION_QUEUE` to submit a flash message
as top-right notifications, instead of inline:

**EXT:my_extension/Classes/Controller/MyController.php**

```php
use TYPO3\CMS\Core\Messaging\FlashMessage;
use TYPO3\CMS\Core\Messaging\FlashMessageQueue;
use TYPO3\CMS\Core\Messaging\FlashMessageService;
use TYPO3\CMS\Core\Type\ContextualFeedbackSeverity;
use TYPO3\CMS\Core\Utility\GeneralUtility;

$flashMessageService = GeneralUtility::makeInstance(FlashMessageService::class);
$notificationQueue = $flashMessageService->getMessageQueueByIdentifier(
    FlashMessageQueue::NOTIFICATION_QUEUE
);
$flashMessage = GeneralUtility::makeInstance(
    FlashMessage::class,
    'I am a message rendered as notification',
    'Hooray!',
    ContextualFeedbackSeverity::OK
);
$notificationQueue->enqueue($flashMessage);
```

The recommended way to show flash messages is to use the Fluid ViewHelper `<f:flashMessages />`.
This ViewHelper works in any context because it uses the `FlashMessageRendererResolver` class
to find the correct renderer for the current context.