Documentation

Table of contents

Content images (<img >)

Getting started with Content images

Sign up for a 30-day trial account and register your domain to start using responsive.io on your website. Next follow these simple steps:

  1. Include our minified Javascript file.

    Place it at the bottom of your page, just before the closing body tag

    <script src="//src.responsive.io/r.js"></script> </body>

    The order of scripts on your page is optional but responsive.io will only detect images present in the markup at the time the browser reaches our script.

  2. Replace the src attribute on your images with data-src.

    Example:

    <img data-src="http://path/to/image.jpg" alt="My responsive image" />

    Make sure your original images are at least 2x of their maximum size to enable retina quality on high pixel density screens.

    The path in the data-src attribute needs to be publicly accessible on the internet, so our servers can pick it up.

    If you are developing on localhost, relative image paths will be ignored by responsive.io. However, it will be picked up when releasing to a public server.

    To use responsive.io on localhost use absolute paths to images pointing to your live server:

    • Works: http://mydomain.com/img/mypic.png
    • Ignored: http://localhost/img/mypic.png
    • Ignored: /img/mypic.png
  3. Style the image using CSS

    responsive.io respects the styles applied to each image element. It doesn’t force you to specify any custom style attributes, instead it picks up the style you’ve already specified using normal CSS or image attributes.

    			
    <style>
        img {
            max-width: 100%;
        }
    </style>
    		

    Styles are calculated by the browser in the following priority:

    1. Inline style attribute on the image element
    2. External Stylesheets & inline style tags
    3. Image element width/height attributes

    Note: if you don’t specify an image style, the responsive image will be displayed in its natural full size - just like a normal HTML image.

Handling Non-Javascript users

Almost all browsers have Javascript enabled but for accessibility & SEO use the following approach as a fallback for non-Javascript browsers:

		
<img data-src="http://mydomain.com/path/image.jpg" alt="My responsive image" />
<noscript>
     <img src="fallback-image.jpg" alt="This is the fallback image">
</noscript>

Preventing Flash of Unstyled Content

A flash of unstyled content (FOUC) happens when elements on a web page appear briefly unstyled prior to loading external assets. This is more common on slow bandwidths or complex web pages.

In the case of responsive.io, img element styles may appear before images starts to load. To prevent this from happening, put the following CSS rule close to the top in your stylesheets.

		
img[data-src] {
    visibility: hidden;
}
	

responsive.io will make sure each image is set to visible just as the browser starts to load it.

CSS Background Images

Overview

Using responsive.io for CSS backgrounds, images are scaled to fully cover areas (same way as background-size: cover) with additional benefits:

Check out our demo page to test it in action.

Getting Started with CSS Background images

Sign up for a 30-day trial account and register your domain to start using responsive.io on your website. Next follow these simple steps:

  1. Include our minified Javascript file.

    Place it at the bottom of your page, just before the closing body tag

    <script src="//src.responsive.io/r.js"></script> </body>

    The order of scripts on your page is optional but responsive.io will only detect images present in the markup at the time the browser reaches our script.

  2. Use data-bg-src attribute on elements to include background images.

    Example:

    <div data-bg-src="http://path/to/image.jpg"></div>

    Make sure your original images are at least 2x of their maximum size to enable retina quality on high pixel density screens.

    The image in the data-bg-src attribute needs to be publicly accessible on the internet, so our servers can pick it up.

    However, if you are developing locally or without images being publicly accessible - it will look the same. Optimization will kick-in when images go on a public server.

  3. Specify size for the background image element

    The element needs to be given a height as normally with CSS.

    
    div {
        height: 3em;
    }

You're done.

Focal-point cropping

Automatically crops your images to fit the background image element based on the focus point. Example:

Focus point cropping

Focus point is by default at the center point of the images. We can set it to any place we like. Example:

<div data-bg-src="/big-image.jpg" data-crop-focus="top left" ></div>

Its also possible to set the focus value using percentages:

<div data-bg-src="/big-image.jpg" data-crop-focus="30% 60%" ></div>

Smart zoom

In many cases its useful to zoom-in on specific areas within images on smaller viewports. Example:

Smart zoom

Here is what the syntax looks like using our zoom feature.

<div data-bg-src="/big-image.jpg" data-zoom ></div>

The default data-zoom value is "320px 120%, 767px 100%".

The syntax can be a bit hard to digest, but we didn’t want to put limits on your creativity. Example:

<div data-bg-src="/big-image.jpg" data-zoom="320px 200%, 768px 100%" ></div>

This syntax translates to a human language like this: Up to 320px image width, zoom level is 200%. Going to 100% (normal) at 768px image width.

The image will be zoomed in on the default focal point using the data-crop-focus. Note that this is a mobile-first approach and the service will interpolate all the zoom values in between.

Advanced zoom

responsive.io allows for multiple zoom levels to be specified at once with the following syntax. This is useful for advanced use cases where we like to change the image at multiple breakpoints.

<div data-bg-src="/big-image.jpg" data-zoom="320px 400%, 500px 100%, 800px 100%" ></div>

The service will now interpolate between all these three values. It’s also possible to turn-off the interpolation and make those sizes in fixed steps, example:

<figure data-bg-src="/big-image.jpg" data-zoom data-zoom-interpolate ="false" ></div>

Zooming is always targeted towards the value set in the data-crop-focus attribute. To make the syntax ultra flexible we also made it possible to define the focus for each zoom level.

<div data-bg-src="/big-image.jpg" data-zoom="320px 400% 30% 40%, 500px 100% center center, 800px 100%" />

Setting the focal point on zoom levels overwrites the value in the date-focal-point attribute.

Custom load event

responsive.io triggers a load event on elements with bg-data-src when the background image has loaded.


<div id="myElement" data-bg-src="/big-image.jpg" />

<script>
  var el = document.getElementById('myElement');
  el.addEventListener('load', eventHandler);
</script>

This can be used to show a loader or fade in the background when it is fully loaded.

General

Detecting images added after page load

responsive.io only loads images present in the markup at the time the script is executed.

If you inject image elements or elements with CSS backgrounds after page load using JavaScript, you have to tell responsive.io about it using the refresh() method:


<script>
    // create image element
    var img = document.createElement('IMG');
    document.documentElement.appendChild(img);

    // load image using responsive.io
    img.setAttribute('data-src', 'myimage.jpg');
    ResponsiveIO.refresh(img);
</script>
	

Note: Above is the recommended approach.

Find and refresh all images on page

Used when you don't have reference to the image that was injected or changed.

		
<script>
    ResponsiveIO.refresh();
</script>
	

Note: This will re-check the size of all images on the page, but only new images and images that are wider than on previous load are downloaded. Calling this function to detect images that have changed size is normally not needed since it's triggered automatically by the window.onresize event.

Disable WebP

By default responsive.io will serve WebP images to browsers supporting the image format.

To disable WebP, set the data-webp attribute to false on image elements or elements using css background images:

<img data-src="http://mydomain.com/image.jpg" data-webp="false" alt="My responsive image" ></div>

Or:

<div data-bg-src="http://mydomain.com/image.jpg" data-webp="false" />

To disable WebP globally, add this to your markup before including our Javascript file:

<script>
    var ResponsiveIO = {
        webp: false
    };
</script>

Note: Data attributes overwrite the global Javascript configuration for individual elements.

Disable Retina/HiDPI Support

By default responsive.io will serve larger images to devices with Retina and HiDPI support.

To disable retina, set the data-retina attribute to false on image elements or elements using css background images:

<img data-src="http://mydomain.com/image.jpg" data-retina="false" alt="My responsive image" ></div>

Or:

<div data-bg-src="http://mydomain.com/image.jpg" data-retina="false" />

To disable retina globally, add this to your markup before including our Javascript file:

<script>
    var ResponsiveIO = {
        retina: false
    };
</script>

Note: Data attributes overwrite the global Javascript configuration for individual elements.

Image Quality

By default responsive.io will serve your images in the original quality, meaning lossless compression only.

To make images smaller in file size, its possible to lower the image quality. Set the data-quality attribute to a number between 0-100 (percentages %) on image elements or elements using css background images:

<img data-src="http://mydomain.com/image.jpg" data-quality="80" alt="My responsive image" ></div>

Or:

<div data-bg-src="http://mydomain.com/image.jpg" data-quality="80" />

To lower the quality globally for all responsive.io images, add this to your markup before including our Javascript file:

<script>
    var ResponsiveIO = {
        quality: 80
    };
</script>

Note: Data attributes overwrite the global Javascript configuration for individual elements.

Image Orientation

When users upload images straight from their cameras, they can sometimes display rotated depending on which way the camera was held. By default user generated images are likely to show up like this:

We offer a convenient way for responsive.io to auto correct the rotation of your images on the fly:

<img data-src="image.jpg" data-image-orientation="from-image" />

This attribute tells responsive.io to auto rotate the image to its true orientation:

You can enable this feature globally, for all images on your site, using our JavaScript configuration:

<script>
    var ResponsiveIO = {
        imageOrientation: from-image
    };
</script>

Note: Data attributes overwrite the global Javascript configuration for individual elements.

Development

Logging & Debugging

To enable logging, add this to your markup before including our Javascript file:

		
<script>
    var ResponsiveIO = {
        debug: true
    };
</script>
	

When the debug flag is set to true, responsive.io prints helpful log statements to the browser console about the images detected on your page.

Debug is set to false by default, and we don’t recommend enabling this on your production server.

HTTP status codes

Standard HTTP status codes are used to return information about image requests. The following codes are used:

Error handling

By default we redirect to the original image if there was a problem. However you can configure a custom error handler and hook in your own logic instead:

			
	<script>
	  var ResponsiveIO = {
	    onError: function(imgElement) {
	      // imgElement failed to load
	    }
	  };
	</script>
		

A possible use case is when using responsive.io to proxy unsecure content and need to avoid showing a broken certficate by hiding the image instead.

Browser support

We support all modern browsers on mobile & desktop:

Older browsers will fall back gracefully to your original images. This is fine in most cases since those users are most likely using a desktop computer with better internet connection than mobile users.

FAQ - Frequently Asked Questions