Origami Frontend Components & Services

Readme: o-lazy-load

This component provides lazy loading functionality for images, pictures, iframes, and more. It is powered by the Intersection Observer API to detect when the visibility of elements changes.


Check out how to include Origami components in your project to get started with o-lazy-load.


The most common use case for lazy loading is to delay the loading of images until they enter the viewport. To do this start by adding the component to the document <body>. For each target <img> element add the o-lazy-load and optionally o-lazy-load--transition class names and change the src attribute to data-src. Because these changes will prevent the images from loading without JavaScript it is recommended to only lazy load decorative images which are "below the fold" of the page and you should always consider the features you must provide as part of your core experience.

- <body>
-   <img src="path/to/image.jpg">
+ <body data-o-component="o-lazy-load">
+   <img class="o-lazy-load o-lazy-load--transition" data-src="path/to/image.jpg">

When images load it can cause a jarring reflow of the page. If you are working on a page with a static width you may wish to apply width and height attributes to your images to prevent this. If you are building a responsive site then o-lazy-load provides styles which can reserve a fixed aspect ratio space for content to load into.

By default classes are provided to preserve space for content with either a 16:9, 16:10, 3:2, 4:3, or 1:1 aspect ratio. If you are including o-lazy-load into your own build process you may configure the placeholder classes to generate.

<div class="o-lazy-load-placeholder o-lazy-load-placeholder--16x9">
    <img class="o-lazy-load o-lazy-load--transition" data-src="path/to/image.jpg" alt="">

If you are using the Build Service, or are calculating aspect ratios dynamically, you can also use a placeholder element to apply a percentage based height using the padding hack.

<div class="o-lazy-load-placeholder">
    <!-- Create custom 16:9 placeholder -->
    <div style="padding-bottom: 56.25%;"></div>
    <img class="o-lazy-load o-lazy-load--transition" data-src="path/to/image.jpg" alt="">

To lazy load a <picture> element add the o-lazy-load class and prefix the src and srcset attributes for each of the <source> and <img> elements contained inside:

<picture class="o-lazy-load o-lazy-load--transition">
    <source data-srcset="path/to/image-small.jpg" media="screen and (max-width: 480px)">
    <source data-srcset="path/to/image-medium.jpg" media="screen and (max-width: 800px)">
    <img data-src="path/to/image-large.jpg" alt="">

o-lazy-load is also capable of lazy loading iframes and toggle class names. See the component demos for more information about these features.


No code will run automatically unless you are using the Build Service.
You must either construct an o-lazy-load instance or fire the o.DOMContentLoaded event, which each oComponent listens for.

Note: If the o-lazy-load root is set to the <html> or <body> element o-lazy-load will assume you want to base element visibility on the viewport.

Constructing an o-lazy-load instance

To initialise o-lazy-load programmatically you can import the oLazyLoad class into your script:

import LazyLoad from 'o-lazy-load';

const root = document.documentElement;
const options = {};

const lazyLoader = new LazyLoad(root, options);

The oLazyLoad class constructor accepts two arguments - the root element and a map of options. The current o-lazy-load options are:

All other options will be passed to the intersection observer, so check the IntersectionObserver documentation for more information about its configuration.

Firing an oDomContentLoaded event

To use o-lazy-load declaratively you must start by declaring the root element by appending the data-o-component="o-lazy-load" attribute to it. You can also add options to this element.

    <div class="js-target">…</div>
    <div class="js-target">…</div>
    <div class="js-target">…</div>

In your JavaScript you can then dispatch the o.DOMContentLoaded event:

document.addEventListener('DOMContentLoaded', function () {
    document.dispatchEvent(new CustomEvent('o.DOMContentLoaded'));

Updating observed elements

If you are loading new or extra content into your document, for example using AJAX or building a single-page application, you may need to update the elements being observed. To do this you can call the .observe() method on the o-lazy-load instance you have previously constructed.

import LazyLoad from 'o-lazy-load';

const lazyLoader = new LazyLoad(document.documentElement);

// ... some logic to update the page ...


Calling this method will find all the elements matching the original options and append any new ones to the set to observe.


To include all o-lazy-load CSS make a single call to oLazyLoad:

@include oLazyLoad();

o-lazy-load features may be included granularly using an options $opts map:

@include oLazyLoad($opts: (
    'placeholder': true, // .o-lazy-load-placeholder
    'placeholder-ratios': ((16, 9), (1, 1)), // e.g. .o-lazy-load-placeholder--16x9
    'transition': true // .o-lazy-load--transition

Migration guide

State Major Version Last Minor Release Migration guide
✨ active 3 N/A migrate to v3
⚠ maintained 2 2.0.7 migrate to v2
╳ deprecated 1 1.0 -


If you have any questions or comments about this component, or need help using it, please either raise an issue, visit #origami-support or email Origami Support.


This software is published by the Financial Times under the MIT licence.

Switch component view

GitHub: o-lazy-load@3.1.2

Install o-lazy-load

If using the Build Service, add o-lazy-load@^3.1.2 to your script and link tags.

If using the npm package manager for a Manual Build, run npm install --save-peer "@financial-times/o-lazy-load@^3.1.2".

Help & Support

o-lazy-load is maintained directly by the Origami team. If you have any questions about o-lazy-load or Origami in general, we are happy to help. 😊

Slack: #origami-support
Email: origami.support@ft.com

Feedback / Issues

To report a bug or request features please create an issue on Github. For support or general feedback please get in touch 😊

Slack: #origami-support
Email: origami.support@ft.com