Angular directive for loading responsive image when container (which is preventing reflow) is in viewport.


Angular Core Dependency: ~1.3.0

Module License: MIT

Added by: Sam Deering





Stars: 357

Watchers: 357

Forks: 77

Module Description

Build Status Coverage Status

Angular Lazy Image

Directive for loading responsive/ adaptive image when parent container (which is preventing reflow) is in viewport. Available as bower component for your project. JavaScript only component.


Demonstration component


  1. npm install angular-lazy-image or bower install afkl-lazy-image -p and set this script as a dependency
  2. Add a dependency on afkl.lazyImage in your app module.
  3. See the style.css for some classes you can use (they prevent reflow and are optional)

Directive in html template

<div afkl-lazy-image="// 480w, // 768w, //" 
    class="afkl-lazy-wrapper afkl-img-ratio-1-1 own-classname"></div>

The attributes are using the srcset setup. Your window will determine which image fits best (so the rules are very dynamic using w/h/x). The image will only be set when the parent container scrolls in the viewport (lazy loading) or scrollable directive. During loading a class 'afkl-lazy-image-loading' is set on the container so you can give loading state feedback to your visitor.


  • "afkl-lazy-image": srcset string (required)
  • "afkl-lazy-image-options": (optional object):
    • '{"background": true}' this will set correct background image on container, false by default
    • '{"offset": 200}' this will influence when to start loading the image, 50px by default
    • '{"nolazy": true}' this will set the image at once and only change on resize
    • '{"alt": "caption for image"}' this will set alt attribute on image, empty by default
  • "class" : afkl-lazy-wrapper will use height 0 trick, afkl-img-ratio-1-1 sets correct aspect ratio so container is 100% responsive as well (optional, include css)
  • Using directive afkl-image-container to have a scrollable container


  1. Angular directives don't have any notion of style encapsulation, but Angular is expected to incorporate that functionality eventually. At the moment our optional css is delivered in an own stylesheet.
  2. Check for native browser support
  3. Look at sizes implementation (100vw)
  4. Rewrite pixeldensity to width (new spec), making it simple blog


  • Using bower on corporate network which blocks git protocol run bash git config --global url."https://".insteadOf git://

Grunt tasks

Source file of this bower module is placed at 'src/lazy-image.js'. Our bower content is also available at 'dist/'


  1. Run npm run update-webdriver once to get latest chrome webdriver (e2e)
  2. Install InternetExplorerDriver

Now we can simply run:

  • grunt sample to see the demo offline (live reload from src)
  • grunt unit to start unit test (report in target folder), grunt unitBrowser for debugging purpose
  • grunt e2e to start our end to end test, which uses local chrome, firefox and internet explorer
  • grunt package to make a complete package which validates everything (used when making new package)
  • grunt update to update our Angular lib (defined in package json) and verify if module works with some versions backwards as well
  • grunt ghpages to update our documentation page


This module was made while working on our Travel Inspiration Finder at KLM.

  • version 0.0.11 26-02-2015 Show alt attribute
  • version 0.0.9 18-10-2014 Scrollable container as option, tested for AngularJS 1.28 and 1.3
  • version 0.0.6 25-08-2014 Tested on Chrome, Firefox, Safari, IE8+
  • version 0.0.5 25-08-2014 Added loading feedback to enduser


As AngularJS itself, this module is released under the permissive MIT license.

Your contributions are always welcome. Feel free to ask for new features. Contributions by: SquadraCorse, ledzep2, TimonVS

Module stats last updated: 2018-01-20 15:00:02

Disclaimer: Some data on this page may have been gathered from the authors GitHub respository. If you see any mistakes or outdated information please let us know. Thanks!