Storefront notifications — best practices

Storefront Notifications — Best Practices

Discover insights around specifics of storefront notifications which Magento 2 uses to inform website visitors as well as existing best practices we recommend to be followed and used by Magento developers.

So, let’s get started by checking the interface. The message interface defines the next messages 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 next 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:

Also, 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.

A text message that will be displayed on the storefront does not have any special chars and HTML tags, that is why we will use add<MessageType>Message 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 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

So, in this example, we will check a case when we should display a text message which contains a link to “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 a 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

Thanks for reading and do not hesitate to post your questions if you have them.

Case Studies

Meet our clients

From startups backed by Mark Cuban and Sir Richard Branson, to some of the biggest eCommerce operations in the world, Atwix helps our clients deliver unparalleled eСommerce experiences. We’re proud to work with the following companies: