Magento 2: Add Loader Widget On Page Load (Easy Guide)

Hey everyone! Ever wanted to make your Magento 2 site feel a bit more polished? One cool way to do that is by adding a loader widget that appears while your page is loading. This can give your users a visual cue that something's happening in the background and prevent them from thinking your site is broken. In this guide, we'll explore how to set up a loader widget on the page load event in Magento 2.3.2. Let's dive in!

Understanding the Need for Loaders

Before we get into the how-to, let's talk about why loaders are important. In today's fast-paced digital world, users expect websites to load quickly. If a page takes too long, they might get frustrated and leave. A loader widget provides visual feedback, letting the user know that the page is indeed loading, and their patience is appreciated. It's a simple yet effective way to enhance the user experience. Implementing a loader involves a few key steps, including setting up the JavaScript, configuring the layout, and styling the loader to match your site's design.

Step-by-Step Guide to Implement a Loader Widget

Alright, guys, let's get our hands dirty and start building this loader widget! We'll break this down into manageable steps.

1. Creating the RequireJS Configuration

First off, we need to tell Magento about our JavaScript module. This is done through a requirejs-config.js file. This file maps our custom module to a specific JavaScript file, allowing Magento to load it correctly. Create this file in your custom module's view/frontend directory. Make sure you place it in the view/frontend/requirejs-config.js path. Here's the code you'll need:

// Filename: view/frontend/requirejs-config.js
var config = {
    map: {
        '*': {
            'customLoader': 'Vendor_Module/js/loader'
        }
    }
};

In this snippet, we're mapping the alias customLoader to our JavaScript file Vendor_Module/js/loader.js. Remember to replace Vendor_Module with your actual vendor and module names. This mapping allows us to easily reference our JavaScript module in other parts of our code.

2. Creating the JavaScript File

Now, let's create the JavaScript file that will handle the loader logic. This file will contain the core functionality for displaying and hiding the loader. Create a file named loader.js in the view/frontend/web/js directory of your module. This is where the magic happens! Here's a basic implementation:

// Filename: view/frontend/web/js/loader.js

define([
    'jquery',
    'Magento_Ui/js/modal/modal'
], function ($, modal) {
    'use strict';

    return function () {
        var options = {
            type: 'popup',
            responsive: true,
            innerScroll: true,
            title: 'Loading...',
            buttons: [],
            modalClass: 'custom-loader'
        };

        var popup = modal(options, $('#custom-loader-wrapper'));

        $('#custom-loader-wrapper').modal('openModal');

        $(window).load(function(){
            setTimeout(function(){
                $('#custom-loader-wrapper').modal('closeModal');
            }, 1000);
        });
    };
});

Let's break down this code:

• We define a RequireJS module that depends on jquery and Magento_Ui/js/modal/modal. These are Magento's built-in libraries for handling modals and jQuery functionality.
• We define a function that initializes the loader. This function creates a modal popup with the title "Loading..." and no buttons.
• We use jQuery to open the modal when the page starts loading.
• We use $(window).load() to ensure that the loader is closed only after the entire page has loaded, including all images and other resources. A setTimeout function is used to delay the closing of the modal by 1 second (1000 milliseconds). This provides a smoother transition and ensures the user sees the loader for a brief moment.

This JavaScript code is the heart of our loader widget. It handles the display and dismissal of the loader, ensuring it's visible while the page is loading and disappears once the loading is complete.

3. Creating the Layout File

Next up, we need to add our loader to the page layout. This involves creating or modifying a layout XML file. Layout XML files define the structure of your Magento pages, including the blocks, containers, and other elements that make up the page. We'll add a container for our loader in the default.xml file of your module. This will ensure the loader is displayed on every page of your site. Create the layout file at view/frontend/layout/default.xml with the following content:

<!-- Filename: view/frontend/layout/default.xml -->
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="page.wrapper">
            <block class="Magento\Framework\View\Element\Template" name="custom.loader" template="Vendor_Module::loader.phtml" before="-"/>
        </referenceContainer>
    </body>
</page>

Here, we're adding a block named custom.loader to the page.wrapper container. This block uses a template file loader.phtml, which we'll create in the next step. The before="-" attribute ensures that our loader block is rendered at the top of the page.wrapper container.

4. Creating the Template File

Now, let's create the template file that will contain the HTML for our loader. This file will define the visual appearance of the loader. Create a file named loader.phtml in the view/frontend/templates directory of your module. Here’s a basic HTML structure for the loader:

<!-- Filename: view/frontend/templates/loader.phtml -->
<div id="custom-loader-wrapper" style="display: none;">
    <div class="custom-loader-overlay"></div>
    <div class="custom-loader-content">
        <img src="<?php echo $this->getViewFileUrl('Vendor_Module::images/loader.gif'); ?>" alt="Loading..."/>
        <p>Please wait...</p>
    </div>
</div>

<script type="text/javascript">
    require(['customLoader'], function (customLoader) {
        customLoader();
    });
</script>

In this template:

• We create a div with the ID custom-loader-wrapper to wrap our loader. This div is initially hidden (display: none;) and will be displayed by our JavaScript.
• Inside the wrapper, we have an overlay (custom-loader-overlay) to dim the background and a content area (custom-loader-content) to hold our loader image and text.
• We use $this->getViewFileUrl() to get the URL of our loader image. Make sure to place your loader.gif image in the view/frontend/web/images directory of your module.
• Finally, we use a require statement to load and execute our customLoader JavaScript module. This will initialize the loader when the page is loaded.

5. Adding CSS Styling

To make our loader look good, we need to add some CSS styling. This will ensure the loader is visually appealing and fits seamlessly with your site's design. Create a _module.less file in the view/frontend/web/css directory of your module. Add the following CSS rules:

// Filename: view/frontend/web/css/source/_module.less
.custom-loader {
    .modal-inner-wrap {
        background: transparent;
        box-shadow: none;
    }

    .modal-header {
        display: none;
    }

    .modal-content {
        padding: 0;
    }
}

.custom-loader-overlay {
    position: fixed;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    background-color: rgba(0, 0, 0, 0.5);
    z-index: 1000;
}

.custom-loader-content {
    position: fixed;
    top: 50%;
    left: 50%;
    transform: translate(-50%, -50%);
    z-index: 1001;
    text-align: center;
    color: #fff;
}

Here, we're styling the modal, overlay, and content areas of our loader. The key styles include:

• Making the modal background transparent and removing the box shadow.
• Hiding the modal header.
• Positioning the overlay to cover the entire screen with a semi-transparent black background.
• Positioning the loader content in the center of the screen.

6. Upload Loader Image

Remember that loader.gif we referenced in the template? You'll need to upload that image to your module's view/frontend/web/images/ directory. You can use any loading animation you like; just make sure the path in your loader.phtml file matches the actual location of your image.

7. Enable the Module and Clear Cache

Last but not least, you'll need to enable your module and clear the Magento cache. This ensures that Magento recognizes your new module and loads the changes. Run the following commands in your Magento root directory:

php bin/magento module:enable Vendor_Module
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush

Replace Vendor_Module with your actual module name. These commands enable the module, run database upgrades, compile the dependency injection configuration, deploy static content, and flush the cache. Clearing the cache is crucial to ensure that Magento picks up the changes you've made.

Conclusion

And there you have it! You've successfully implemented a loader widget on the page load event in Magento 2.3.2. This simple addition can significantly enhance the user experience on your site. Remember, user experience is key to keeping your customers happy and engaged.

Implementing a loader widget might seem like a small detail, but it's these small details that add up to create a polished and professional website. By providing visual feedback to your users, you're showing them that you care about their experience and are working to make their browsing journey as smooth as possible. Keep experimenting with different loader styles and animations to find what works best for your site. Good luck!

Pro Tip: You can customize the loader further by adding different animations, text, or even progress bars. Feel free to get creative and make it your own!