Loader widget

The Loader widget blocks page content (all content or a part of it). Its intended use is blocking content when an Ajax request is being sent, but it can be initialized for non-Ajax tasks as well.

The Loader widget source is lib/web/mage/loader.js.

Initialize

For information about how to initialize a widget in a JS component or .phtml template, see the Initialize JavaScript topic.

The following example shows how to instantiate the Loader widget:

Copy
$('#example').loader({
    icon: 'path to icon'
});
Copied to your clipboard
$('#example').loader({
    icon: 'path to icon'
});

Where:

• #element is the selector of the element for Loader is initialized.

Copy
<script>
require(['jquery', 'loader'], function ($) {
    'use strict';

    $('#example').loader({
        icon: 'path to icon'
    });
});
</script>
Copied to your clipboard
<script>
require(['jquery', 'loader'], function ($) {
    'use strict';

    $('#example').loader({
        icon: 'path to icon'
    });
});
</script>

Options

icon

The URL to the loader image. This image is displayed when the widget is active; that is, between the ajaxSend and ajaxComplete events.

Type: String

Default value: No image by default.

template

HTML wrapper for the output, or a DOM element selector.

Default value:

Copy
<div class="loading-mask" data-role="loader">
    <div class="loader">
         <img alt="<%- data.texts.imgAlt %>" src="<%- data.icon %>">
        <p><%- data.texts.loaderText %></p>
    </div>
</div>
Copied to your clipboard
<div class="loading-mask" data-role="loader">
    <div class="loader">
         <img alt="<%- data.texts.imgAlt %>" src="<%- data.icon %>">
        <p><%- data.texts.loaderText %></p>
    </div>
</div>

texts

An object that contains translations for loader text:

• texts.loaderText: The text that is displayed under the loader image. Default value: 'Please wait...'
• texts.imgAlt: The text that is set as the alt attribute value of the loader image. Default value: 'Loading...'

Methods

show()

Show the loader.

Invoke the show method:

Copy
$("#element").loader("show");
Copied to your clipboard
$("#element").loader("show");

hide()

Hide the loader.

Invoke the hide method:

Copy
$("#element").loader("hide");
Copied to your clipboard
$("#element").loader("hide");

Events

Loader is subscribed to the following events:

• processStart
• processStop

processStart

Display the loader. Can be triggered on any page element.

Start show loading:

Copy
$("body").trigger('processStart');
Copied to your clipboard
$("body").trigger('processStart');

The following is an example of adding a callback to processStart event.

Copy
var callback = function () {
    // do something before showing the loader
};

$("body").on('processStart', callback);
Copied to your clipboard
var callback = function () {
    // do something before showing the loader
};

$("body").on('processStart', callback);

processStop

Hide the loader. Can be triggered on any page element.

Stop show loading:

Copy
$("body").trigger('processStop');
Copied to your clipboard
$("body").trigger('processStop');

The following is an example of adding a callback to a processStop event.

Copy
var callback = function () {
    // do something before hiding the loader
};

$("body").on('processStop', callback);
Copied to your clipboard
var callback = function () {
    // do something before hiding the loader
};

$("body").on('processStop', callback);

Code Sample

The following example shows the loader when a processStart event triggers for the #loader-example element.

Copy
<div id="loader-example" data-mage-init='{"loader": { "icon": "{store URL}/static/{static version}/frontend/Magento/luma/en_US/images/loader-2.gif"}}'>
    <h3>Block</h3>
    Lorem ipsum dolor sit amet, consectetur adipisicing elit. Dignissimos itaque numquam placeat quam recusandae velit voluptas. Ad architecto asperiores eos eveniet id nostrum officiis saepe soluta totam voluptate! Debitis, quibusdam.
</div>
<script>
require(['jquery', 'loader', 'domReady!'], function ($) {
    'use strict';

    $('#loader-example').trigger('processStart');
});
</script>
Copied to your clipboard
<div id="loader-example" data-mage-init='{"loader": { "icon": "{store URL}/static/{static version}/frontend/Magento/luma/en_US/images/loader-2.gif"}}'>
    <h3>Block</h3>
    Lorem ipsum dolor sit amet, consectetur adipisicing elit. Dignissimos itaque numquam placeat quam recusandae velit voluptas. Ad architecto asperiores eos eveniet id nostrum officiis saepe soluta totam voluptate! Debitis, quibusdam.
</div>
<script>
require(['jquery', 'loader', 'domReady!'], function ($) {
    'use strict';

    $('#loader-example').trigger('processStart');
});
</script>

Result

The loader shows when a processStart event triggers for the #loader-example element.

Last updated 9/11/2023

Was this helpful?

Yes

No