This section describes our image mixins and how we use asynchronous image loading.

Adding images

When adding inline images to a document you should always use the +image Jade mixin.

image(platform, lgSize, lgSrcs, smSize, smSrcs, xsSize, xsSrc)
  • platform - String. The platform that the image is to be shown on. Value options are 'xs', 'sm', 'lg'. This value should generally be provided by the application that uses the mixin, and should only be hardcoded in special cases.

  • lgSize/smSize/xsSize - Array of integers. The size of the image (x,y) per platform. Both width and height are required.

  • lgSrcs/smSrcs/xsSrc - Array of strings. The src(s) for the image. The first value of the array is 1x, the second is 2x. 2x is optional. See High DPI section for more information.

Please note that on xs any src other than the first is ignored - 2x is not available on xs.


+image('lg', [400,100], [''])


+image('sm', null, null, [400,100], [''])


+image('xs', null, null, null, null, [400,100], [''])

all platforms

This is the typical use case for the mixin. Size and src parameters are provided for more than one platform, and the platform to render for is provided by the application in which the mixin is used.

This demo site does not perform platform detection, and therefore the lg variant will always be displayed in the example below.

 [400,100], [''],
 [300, 75], [''],
 [200, 50], [''])

Asynchronous image loading

All calls to the image mixin that do not have a platform of xs will automatically be lazy loaded using js.

If you must circumvent lazy loading for some reason it is possible to specify the platform as 'xs'. This will remove the option for a 2x version.

+image('lg', [400,100], [''])

Live demo

High DPI

To add a high resolution version of image simply pass it as the second value in the src array. The JavaScript image loader will figure out wether the device has a high dpi screen. If the srcset attribute isn't supporrted it will attempt to set the correct image as the src based on window.devicePixelRatio property.
  null, null,
  [200, 60], ['', '']

Live demo

Async images and indicators

To enable an indicator for an image, simply set the data-indicator attribute to true. An indicator will then show during image loading. See the async images demo below for examples on how it looks in action. (You may need to throttle your connection to see the effect)

Async Images Live Demo

The images below are loaded asynchronously as they become visible in the viewport. Scroll fast to see them load!

Deferred image rendering

To enable deferred image rendering for an image (the image will not be rendered until loaded in its entirety), set the data-defer attribute to true.

Deferred image rendering example

The images below are fairly large and should take considerable time to load. When loaded, they should appear 'instantly'. (You may need to throttle your connection to see the effect)

Deferred - no indicator

Deferred - with indicator