Guides

Javascript (Gumlet.js)

Easily integrate Gumlet with any webpage using this tiny library

Suggest Edits

Overview

Gumlet.js allows developers to deliver responsive images to end-users easily. This lets you write a simple <img> tag without any complicated src-sets & size. Gumlet.js parses the <img> tag on-load to append the image src URL with the correct width for the users' device. Gumlet's image transform service processes the URL and resizes your image on the fly.

Features

  • Pure JavaScript with zero dependencies
  • 5 KB minified and gzipped
  • Works with all frontend frameworks like Angular, React or Vue.js
  • Uses IntersectionObserver API for reduced CPU usage
  • Support for <picture> element
  • Support for setting background-image CSS property
  • Automatic quality selection based on connection speed
  • SEO Friendly: Detects search engine bots and reveals all images at once for best SEO

Installation

The best and easiest way to install gumlet.js is by including it in <head> section of all your pages.

<script type="text/javascript">
    window.GUMLET_CONFIG = {
        hosts: [{
            current: "{{example.com}}",
            gumlet: "{{mysubdomain}}.gumlet.io"
        }],
        lazy_load: true
    };
    (function(){d=document;s=d.createElement("script");s.src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gumlet.min.js";s.async=1;d.getElementsByTagName("head")[0].appendChild(s);})();
</script>

Please replace {{mysubdomain}} in the above code to the subdomain created by you on Gumlet. Please also replace {{example.com}} with the domain from where images are currently being served.

Once the above steps are complete, your users will automatically start getting responsive images! Yes, it's that simple.

However, we recommend making the following changes to <img> tags to make images even more optimized.

Rename img src="" to data-src=""

If you are currently serving images from a CDN or your web server, the chances are that you would have all <img> tags with src attributes. We recommend you change them to data-src attributes. For example:

<!-- Current image tag -->
<img src="https://demo.gumlet.io/logo.png" alt="Gumlet Logo">

<!-- Image tag required for Gumlet -->
<img data-src="https://demo.gumlet.io/logo.png" alt="Gumlet Logo">

If you don't do this step, whenever a user loads a page, the browser will request an image available in the src attribute, and as soon as gumlet.js processes it and it cancels the request. This is very inefficient and should be avoided. Once you set the data-src attribute, gumlet.js will ensure that the browser loads only the required image, and no extra requests are made to the server.

👍

Gumlet is live now!

This is all that was needed to deliver responsive images to your users.

How does it work?

Let us describe how gumlet.js works under the hood. We use capabilities available in modern browsers to deliver responsive images.

If you write animg tag such as below,

<img data-src="https://demo.gumlet.io/logo.png" alt="Gumlet Logo">

Gumlet.js will generate HTML something like the following:

<img data-src="https://demo.gumlet.io/logo.png"
  alt="Gumlet Logo"
  src="https://demo.gumlet.io/logo.png?w=300" >

Since Gumlet can generate as many derivative resolutions as needed, gumlet.js programmatically calculates an image's required dimensions. Once that is determined, gumlet.js puts the needed information in src tag.

Dynamic Images

Gumlet.js observes all existing images for changes to "src" tags. If any change is detected, the image is automatically processed.

Gumlet.js also monitors if any new image is added to the DOM. If a new image is detected, the image is processed automatically.

Usage

Lazy load images

This library supports lazy loading images. You can pass lazy_load parameter while initializing gumlet.js.

<script type="text/javascript">
    window.GUMLET_CONFIG = {
        hosts: [...],
        lazy_load: true
    };
</script>

If you want to disable lazy-load for certain images, you can set data-gmlazy="false" for that element, and the library will load the image immediately for that element. E.g.

<img data-src="https://demo.gumlet.io/sea.jpeg" data-gmlazy="false" >

Web-Proxy source

If you use a web proxy source for your image distribution, you can set the following config parameter such that gumlet.js generates URLs for the proxy source.

<script type="text/javascript">
    window.GUMLET_CONFIG = {
        hosts: [...],
        proxy: true
    };
</script>

Enable srcset Generation

If you want to enable the generation of srcset for images, you can add the following config parameter.

<script type="text/javascript">
    window.GUMLET_CONFIG = {
        hosts: [...],
        srcset: true
    };
</script>

Set the image as the background

Gumlet.js also supports setting images as background for any HTML element. You need to set the data-bg attribute for an element, and the correctly sized image will be set as background-image CSS property. For example:

<div>
    <span data-bg="forest.jpeg" style="background-repeat: no-repeat;background-size: contain; width: 300px;"></span>
</div>

<!-- above code will set
     background-image: url('https://demo.gumlet.io/forest.jpeg?w=300')
     CSS attribute
-->

Load images from multiple domains

If you are loading images from multiple domains, you need to configure Gumlet.js to serve images from different domains. A sample configuration is given below.

<script type="text/javascript">
    window.GUMLET_CONFIG = {
        hosts: [{
            current: "{{example.com}}",
            gumlet: "{{mysubdomain}}.gumlet.io"
        }, {
            current: "{{another_example.com}}",
            gumlet: "{{another_subdomain}}.gumlet.io"
        }]
    };
</script>

Client-Side WebP Detection

Gumlet automatically detects WebP support from the server side and delivers a WebP image whenever possible. When you pass format=auto URL parameter, Gumlet service performs server-side WebP detection.

This client-side implementation is helpful when you can not use the server-side WebP detection. You can pass the auto_webp parameter to the config. For example:

<script type="text/javascript">
    window.GUMLET_CONFIG = {
        hosts: [...],
        auto_webp: true
    };
</script>

This will append the required query parameter format=webp after detecting support in the browser. More information on this can be found here.

Ignore images

If you want to exclude some <img> tags from being processed by gumlet.js, you can set data-gumlet="false" attribute and this library will not process it. E.g.

<img src="https://demo.gumlet.io/sea.jpeg" data-gumlet="false" >
<!--
    Above image will never be processed by Gumlet and will be
    left as it is.
-->

Library Config Options

OptionMeaningDefault ValueExample Value
hostsAn array containing objects with attributes current and gumlet hostnames. Images with matching current hosts will be replaced with gumlet hostnames. This is a required parameter.undefined[{ current: "webserver.com", gumlet: "simple.gumlet.io"}]
elements_selector_imgCSS selector for the elements for which the image has to processed"img"".gumlet_img"
elements_selector_bgCSS selector for the elements for which the background image has to be set"[data-bg]"".gumlet_bg"
elements_selector_pictureCSS selector for the picture elements to process with Gumlet.js."picture > source"".gumlet_pic"
data_srcThe name of the data attribute containing the original image source, excluding the "data-" part. E.g., if your data attribute is named "data-src", pass only"src""src""original"
data_bgThe name of the data attribute containing the background image source, excluding the "data-" part. E.g., if your data attribute is named "data-bg", just pass "bg""bg""background"
auto_qualityEnables automatic quality depending on connection speed. When enabled, it requests reduced image quality on slow connection types. This flag also reduces the quality when "save data" is enabled in chrome.truefalse
max_dprMaximum DPR to apply when processing imagesundefined2.5
auto_webpFlag to indicate whether format=auto should be appended to URLs after detecting WebP support in the browser.falsetrue
srcsetFlag to indicate whether the library should set srcset and sizesfalsetrue
lazy_loadEnable or disable lazy loading of images.falsetrue
thresholdThe number of pixels representing the outer distance off the scrolling area from which to start lazy loading the images.300100
proxyEnable this flag if your distribution uses a web proxy source.falsetrue
width_from_imgTake width from <img> tag's width attribute.falsetrue
use_native_lazy_loadUse browser's native lazy load for supported browsers.truefalse
default_paramsDefault parameters to be passed to all image URLs{}{compress: true}

Browser Support

We certify this library to work on the following browsers. On the browsers which are not supported, this library will fall back to delivering images as it is.

🚧

IE 11 support

Version 2.0 of this library is the last version that supports IE 11. If you need IE 11 support, please use that version.

BrowserMinimum Supported Version
Chrome29
Firefox27
Safari8
EdgeAll versions
Opera16
UC Browser10
iOS Safari8
Android WebviewAndroid 4.4+
Android BrowserAndroid 4.4+

Updated 24 days ago