JSLazyLoading plugin for Joomla!

JSLazyLoading is a lightweight performance-oriented plugin for lazy loading and multi-serving of images, that is intended for client-side optimization. Written in pure JavaScript, the plugin does not depend on third-party libraries, such as jQuery. The plugin delays the loading of images that are outside the viewport until a user scrolls to their position in the document.

The multi-serving option allows to display images dinamically, according to the device screen width or the device screen density. Retina mode is intended to display high-density images if the device screen density is high enough. In this mode high-quality images are loaded on demand without waiting of entire page load. In contrast, if you want to speed up your site to the maximum and you do not need Retina support, you can set smaller light-weight images to be displayed in mobiles and tablets instead of large images.

This plugin can reduce network traffic and increase page load speed, which is very helpful if a user has slow internet connection. Different client-side and server-side options allow you to optimize the performance and usability of your website. The plugin can work with AJAX navigation and dynamic modules, such as sliders and carousels. It compatible with both modern and older browsers.

Open the demo page
Get this plugin
Read the change log

Installation and usage:

1. Install the plugin via Joomla Extension Manager.
2. Open the plugin page.
3. Select the options you need.
4. Enable the plugin.

Server-side settings

Standard mode: the plugin modifies the HTML output on the fly, changing the “src” attribute of an image to a custom “data-src” attribute. Thus, you do not need to edit the original HTML.

<!-- Standard mode allows you to keep your HTML unchanged: -->

<img src="/example-1.jpg" />

<!-- The image above will be involved in lazy loading. While your HTML will not be changed, the plugin will modify the HTML output on the fly: -->

<img data-src="/example-1.jpg" src="/folder/placeholder.gif" />

Reverse mode: the plugin ignores images with the “src” attribute and allows lazy loading only for the images that have the “data-src” attribute. This attribute is set manually in the original HTML source. In reverse mode, the plugin does not modify the output.

<!-- This image will be ignored and shown in the ordinary way: -->

<img src="/example-2.jpg" />

<!-- This image will be involved in lazy loading -->

<img data-src="/example-2.jpg" />

Global exclusions

With this option you can exclude specific components, component views, layouts or articles from lazy loading. If the entered values match global Joomla! variables, images will be loaded in an ordinary way. If the rewriting mode option is set in the reverse value, the “data-src” image attributes will be rewritten to the “src” attributes. The parameters must be separated by an ampersand character (&), the parameter names and values are separated by an equal sign (=). The parameter groups are separated by commas. It is possible to use masks, such as (x|y|z). Examples:

Modal window exclusion: tmpl=component
Front-end editor exclusion: view=form
Exclusion of menu items: Itemid=(13|25|77)
Entire exclusion of a component: option=com_users

Exclusion of component views and layouts: option=com_content&view=category, option=com_content&view=category&layout=blog
Exclusion of articles: option=com_content&view=article&id=(10|101|3)

Exclude/Include criteria

If exclude is selected, this will exclude images that have specified CSS classes from lazy loading. If include is selected, lazy loading will be enabled only for the images that correspond to specified components, component views, or articles, as well as for the images that have certain CSS classes.

Use in admin panel

If this setting is enabled, the plugin will work in the admin panel. It's recommended to use this setting only alongside the setting 'Exclude/Include criteria' with the param 'Include' selected, so that the plugin works in certain components or images having certain CSS classes. Otherwise, this can break down the admin panel.

Exclude/Include images by CSS

Exclude/Include images from/to lazy loading by CSS classes. The CSS classes must be separated by commas. It's not recommended to set more than 5 classes, as it can reduce performance.

Excluding HTML tags

If enabled, all the images or the containers with images between certain tags or comment blocks will be excluded from lazy loading.

<!-- All the images inside the comment block will be ignored: -->

<!--[NOLAZY]-->

  <div>
  
    <img src="/image-1.jpg" />
    <img src="/image-2.jpg" />
	
  </div>
  
  <div>
  
    <img src="/image-3.jpg" />
    <img src="/image-4.jpg" />
	
  </div>
  
<!--[ENDNOLAZY]-->

<!-- Another example. All the images inside the custom tags will be ignored: -->
    
<no-lazy>

    <img src="/image-5.jpg" />
    <img src="/image-6.jpg" />
	
</no-lazy>

Background images support

This option determines whether to load background images in lazy mode. If enabled, background images will be lazy loaded in a global way. Fade-in effect, loader placeholder and other image specific options are not available for background images.

No JavaScript support

If enabled, each image in the output, before modifying, will be duplicated and wrapped into a <noscript> container, so that the users that have JavaScript disabled can view these images. Also, we need to hide blanked images because they consume additional space; therefore, we dynamically add a CSS rule that is also wrapped into <noscript> container.

<head>
  
  <!-- If JavaScript is disabled, the blanked images will be hidden -->
  
  <noscript>
    <style type="text/css">.jsll-noscript + img {display: none}</style>
  <noscript>
  
</head>

<!-- Your HTML: -->

<img src="/image-1.jpg" />
<img src="/image-2.jpg" />


<!-- The original images will be automatically cloned and wrapped into a <noscript> container, so the HTML output will be the following: -->

<noscript class="jsll-noscript">
  <img src="/image-1.jpg" />
</noscript>

<img data-src="/image-1.jpg" src="/folder/placeholder.gif" />

<noscript class="jsll-noscript">
  <img src="/image-2.jpg" />
</noscript>

<img data-src="/image-2.jpg" src="/folder/placeholder.gif" />

Set placeholder

According to the HTML standards, an image must have the “src” attribute. In lazy mode, this attribute must have a placeholder image. You may set a placeholder manually or allow the plugin to perform the work automatically. When an image is in the viewport, the placeholder image is changed to the original source from the custom “data-src” attribute. This option is intended for the reverse mode. In the standard mode, the placeholder is always set automatically.

<!-- In the reverse mode, your need to rename the “src” attribute to the custom “data-src” attribute: -->
 
<img data-src="/example.jpg" />


<!-- The output when the “Set placeholder” option is enabled: -->
 
<img src="/folder/placeholder.gif" data-src="/example.jpg" />


<!-- The output when the “Set placeholder” option is disabled: -->
 
<img data-src="/example.jpg" />

Search engine optimization

As the images involved in lazy loading do not contain the original source, they cannot be indexed by search engines. For this reason, it is recommended not to modify the HTML output when a bot is crawling a page. To recognize a bot, we can check the client's User-Agent. You can specify any substring to be excluded from lazy loading. In the standard mode, the plugin will be stopped if a match has been found. In contrast, when in reverse mode, the plugin shows a bot the original image source instead of a placeholder. Be careful with this parameter: you may also disable the plugin in browsers if you enter, for example, something like “chrome”.

Debug

Use this setting to check PHP script execution time. You can display the result in the JavaScript console or at the top of a page if JavaScript is disabled. Do not forget to close your website in the latter case, while debugging. To see how it works, open the JavaScript console.

Multi-serving of images

Image multi-serving is a way to display images dynamically according to a client device type. Retina mode is intended to display high-density images if the device screen density is high enough. In this mode high-quality images are loaded on demand without waiting of entire page load. In contrast, if you want to speed up your site to the maximum and you do not need Retina support, you can set smaller light-weight images to be displayed in mobiles and tablets instead of large images. The multi-serving can be manual and automatic. Automatic mode allows to keep the original HTML unchanged. The plugin will display a high-density or resized analogue image only if the screen parameters of a device match a breakpoint value. There can be several breakpoints, in which case, the plugin will output the image that corresponds to the closest breakpoint.

Multi-serving method

There are two approaches to multi-serving – according to the client device screen width, and according to the client device screen density. In the first instance, the smaller (resized) images will be displayed if the device screen width is less than or equal to the value of a breakpoint. In the second instance, the plugin will display high-density analogues, if the device screen density is more than or equal to the value of a breakpoint.

Manual mode

<!-- Set data-* attributes that identify alternative sources for multi-serving. Your HTML in the manual mode must be the following: -->

<img src="/example.jpg" data-src-small="/example-small.jpg" data-retina2x="/example-retina2x.jpg" />

Automatic mode

<!-- Do not set data-* attributes! Just copy an image, resize it, add a postfix to the filename, and put it in the same folder as the original image. The postfix must start with an underscore (_) symbol. If an analogue does not exist, the plugin will output the original image. Your HTML in the automatic mode is: -->

<img src="/files/image.jpg" />

files/
  [..]
  image.jpg
  image_small.jpg
  image_medium.jpg
  image_retina2x.jpg

Image handler

This setting is intended for automatic multi-serving mode. If you use Apache, it is recommended to set an Apache handler – it works faster than a PHP handler and does not changes the file extension. If you do not use Apache or mod_rewrite, or if Apache handler causes errors, you can set the PHP handler instead.

Client-side settings

Dynamic mode

This setting determines whether to load hidden images. If the dynamic mode is enabled, images with CSS “display:none” or “visibility:hidden” property are not loaded, as well as images that are outside lateral viewport borders – they might be hidden with the overflow property (e.g. carousels, sliders). If their display status changes, they will be reexamined and loaded when they are in the viewport.

Enabling the dynamic mode also enables a standalone listener that examines the status of all hidden images 3 times per second regardless of scroll and resize events triggering the examination of the visible image collection. If this option is disabled, all hidden images will be loaded on page load. Additionaly, you can set the threshold of lateral viewport borders “X-axis” to load the images before they achieve the side borders.

Top border

Do we use the top viewport border in the image visibility examination? If yes, images that are higher than the top viewport border are not loaded. By default, only the bottom border is used.

Threshold range (Y-axis)

If you want images to load before they achieve the bottom viewport border, use this option. Setting the threshold range to 300 causes an image to load 300 pixels before it appears in the viewport. If the “Viewport top border” setting is enabled, this option also determines the top border.

Threshold range (X-axis)

This setting determines lateral viewport borders. The X-axis threshold can be specified only if the “Dynamic mode” is enabled.

Fade-in effect

Determines whether to display images by fading them to opaque. The fade-in effect is based on CSS3 transition and is available only for browsers that support CSS3. The main goal of lazy loading is to improve performance, so it is not reasonable to use decoration effects based on multiple JavaScript recursions or intervals. Therefore, it is disabled in older browsers.

Effect duration

This setting refers to the fade-in effect and determines the number of milliseconds to run the animation (the default value is 400).

Loader image

Enable/disable the display of a loader image while an original image is being loaded. If you do not want to use the default loader image, you can set an alternative one.

Background colour

Background colour of the placeholder while the original image is being loaded. By default, the background is transparent.

Soft Mode

As the images involved in lazy loading do not contain the original source, the client browser “does not know” the image height until the image is loaded. As a result, the content may “jump” as the image loads because the browser changes the placeholder to another image. To prevent this behaviour, you can specify the image height in CSS; however, this is not possible in some cases, e.g. if you have a responsive layout.

With the soft mode enabled you do not have to set the height of your images; the height property will be set for images dynamically, according to the container width. The soft mode only works for images that have the “width” and “height” attributes (the plugin calculates the image dimensions according to the values of these attributes).

Sequential Loading

This parameter determines whether to force the loading of images that are outside the viewport (disabled by default). While a visitor is viewing the content, images can be loaded at an interval specified in the field “Loading interval”. You may also set a zero interval, in which case, all the images will be loaded immediately one after another.

Client-side exclusions

You can exclude modules, HTML containers, or images that have certain CSS classes or ID from lazy loading. The attribute values must be separated by commas, for example: .moduletable, #my-image, .image-container. When the DOM is ready, all images that have these attribute values, as well as images inside containers that have these attribute values, will be loaded immediately. The exclusions are applied on the client side, not on the server side – they are still processed by PHP, but is not processed by the JavaScript plugin. If you need exclude these images completely, you should use server-side options, such as excluding tags or image exclusion by CSS classes.

Ajax Listener

Restart the plugin when the browser sends an HTTP request if you need the new images to load in lazy mode (only images with a data-attribute will be involved). Another way to include new images in the plugin scope is to use a public method “refresh” (see the manual for the raw JavaScript plugin).