Lazy loaded images with placeholders and noscript fallback
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


lazy-images-rails is a Rails plugin that augments the standard image_tag helper to provide instant placeholders for images while the actual image is being loaded.


Due to the asynchronous nature of images in web pages, page content is often rendered a long time ahead of images. In many cases this leads to content jumping downwards once an image above it has been loaded.

This is very annoying when you've found a thing to click/tap on, and just before you do, it moves out of the way. Especially when it causes a misclick/tap on something unentended.

This problem can be solved in many ways, but the solution provided by this plugin, is to simply use a placeholder until the real image is loaded.


Instead of rendering a bare <img /> tag, the Rails image_tag helper renders an SVG placeholder behind the image while it is loading. This placeholder takes up the same space as it's constituent image.


Include the supplied css asset in the manifest, application.css:

*= require lazy_images_rails

Add an image in a view, index.html.erb:

<%= image_tag 'foo.png' %>

In case an image needs to be inserted without a placeholder, since the image_tag helper has been aliased, accessing the unmodified helper is done with the suffix:

<%= image_tag_without_lazy_images 'foo.png' %>

A note about non-square images

Since the image ratio of square images are all the same, by default the placeholder can be used without further ado to take up the same space as the square image it replaces.

If an image however, is not square, it becomes necessary to provide the dimensions explicitly.

The image_tag helper already supports this through the size attribute:

image_tag('foo.png', size: "123x456")

So setting this attribute will affect the placeholder as well and set width and height accordingly in the same manner.

Styling the placeholder

The default placeholder image is a simple graphic of a mountain and a moon. Both have been supplied with targetable classes for individual styling. Create a custom rule with these classes, e.g. (scss):

.rli-wrapper {
  .rli-placeholder {
    background: #fff;

    .moon, .mountain {
      fill: #ddd;

And the constituent paths in the the svg image will be styled accordingly.

Using custom svg as placeholder

The placeholder is stored as a string value in LazyImages::Rails.placeholder, so in order to overwrite the default, create an initializer and set it accordingly, e.g. config/initializers/lazy_images-rails.rb:

custom_placeholder ="#{Rails.root}/app/assets/images/custom.svg")
LazyImages::Rails.placeholder = custom_placeholder

Here assuming you have placed your custom placeholder in app/assets/images/custom.svg.


Ruby tests

rake test