Responsive image tag as a Web Component

the-image is a responsive image tag provided as a Web Component. It allows a single HTML tag to be used for providing multiple variants of an image for different classes of devices and displays. the-image can be used right now, without having to wait for the Responsive Image spec to trickle down to mainstream browsers.


Best viewed side-by-side on two screens of different pixel densities. For example, a Retina tablet and a regular laptop. Make sure to also inspect the elements in your web console!


Before using the-image you may want to read about Polymer Web Components and watch the Web Components video from Google I/O 2013.


Web Components are not yet supported natively in mainstream browsers, and so in order to use the-image you need to include the Polymer polyfill to your HTML pages:

<script src="vendor/polymer.min.js"></script>

You also need to import the component itself:

<link rel="import" href="vendor/the-image.html">


Once the component has been imported, you can use it very similarly to how you would use a regular HTML img tag, with the difference that you can provide this one dimensions and multiple variants of the image:

<the-image mdpi="image.jpg" xhdpi="image@2X.jpg" width="300" height="200"></the-image>

Each usage of the-image tag creates a Shadow DOM fragment with an img tag inside it. This image tag will automatically point to the best image variant for the user's device.

Image size variants

This Web Component follows the Android guidelines for naming the different screen densities supported. In nutshell:

Density DPI Example devices
ldpi 120 budget smartphones
mdpi 160 regular computers
xhdpi 320 retina-class devices