Storefront notifications — best practices

Discover insights into the specifics of storefront notifications that Magento 2 uses to inform website visitors, as well as the existing best practices we recommend for Magento developers to follow and uses.

So, let’s get started by checking the interface. The message interface defines the following message types:

There is also an “exception” message which is tied to error messages and displayed on the storefront in the same color scheme.

Magento 2.1.0 release has deprecated the following methods of Manager Interface because they were not secure:

We recommend avoiding using these methods.

Instead of these methods, developers should use the following ones:

Additionally, new “complex” methods have been introduced:

Examples of usage

For better understanding in which cases a developer should use add<MessageType>Message, and when they should use similar complex methods let’s check the following examples.

Example #1

We need to display a “You deleted the address” text message when the address has been successfully removed from the customer’s address book.

Delete address success screenshot

A text message that will be displayed on the storefront does not contain any special characters or HTML tags; therefore, we will use the addMessage method. And if we are talking about a successfully executed operation then in the add<MessageType>Message <MessageType> should be replaced with a Success word. As a result, we will get — addSuccessMessage:

$this->messageManager->addSuccessMessage(__('You deleted the address.'));

Note, that as an alternative option to display the mentioned message, a developer may use a more complicated approach:

$message = $this->messageManager
        __('You deleted the address.')


For example, we need to highlight an “address” word in the “You deleted the address” text message to be bold. In this case, a developer can use the next code:

$this->messageManager->addSuccessMessage(__('You deleted the address.'));

However, such approach will return the unexpected result and You deleted the <b>address</b>. message will be displayed on the storefront instead:

You deleted the address

As you can see from the screenshot above addSuccessMessage is definitely not a way to display text messages containing HTML tags. For such cases developers must use a complex method, which is described in the next Example.

Example #2

In this example, we will examine a case where we need to display a text message that contains a link to the “customer/account/forgotpassword” pages. That’s a common case when a registered customer tries to register on the website again.

Customer already exists error

The next steps should be taken to display a message on the screenshot.

1. Create a template which will contain a necessary text message:

 * Copyright © Magento, Inc. All rights reserved.
 * See COPYING.txt for license details.

/** @var \Magento\Framework\View\Element\Template $block */
<?= $block->escapeHtml(__('There is already an account with this email address. If you are sure that it is your email address, <a href="%1">click here</a> to get your password and access your account.', $block->getData('url')), ['a']);

2. Use di.xml to add a new element into the message configuration pool:

<type name="Magento\Framework\View\Element\Message\MessageConfigurationsPool">
    <argument name="configurationsMap" xsi:type="array">
      <item name="customerAlreadyExistsErrorMessage" xsi:type="array">
        <item name="renderer" xsi:type="const">\Magento\Framework\View\Element\Message\Renderer\BlockRenderer::CODE</item> 
        <item name="data" xsi:type="array"> 
        <item name="template" xsi:type="string">Magento_Customer::messages/customerAlreadyExistsErrorMessage.phtml</item> 

3. Use message manager to call a customerAlreadyExistsErrorMessage message and set an URL to customer/account/forgotpassword page in Vendor/Module/Controller/Account/CreatePost.php:

        'url' => $this->urlModel->getUrl('customer/account/forgotpassword'),

Note: check the code below to understand how a developer may call a customerAlreadyExistsErrorMessage message without addComplexErrorMessage method:

$identifier = 'customerAlreadyExistsErrorMessage';

$message = $this->messageManager
    ->createMessage(MessageInterface::TYPE_ERROR, $identifier)
            'url' => $this->urlModel->getUrl('customer/account/forgotpassword'),


Final inputs

Thank you for reading, and please don’t hesitate to post your questions if you have any.