Fast, Smooth Image Loading For Better User Experience – Loadr.js

Loadr is a lightweight (~1kb) JavaScript library designed to optimize the loading of large images on web pages. It is useful for websites with many high-resolution images, such as photography portfolios, online stores, or e-commerce websites.

The library initially shows a low-resolution image placeholder while fetching the high-resolution version in the background. Once the high-resolution image is ready, Loadr swaps it in, creating a smoother image-loading experience for your visitors. This avoids the abrupt appearance of high-resolution images or blank spaces during page load.

How to use it:

1. Include Loadr in your project through a local file or a CDN:

<!-- You first need to download the loadr library -->
<script src="/path/to/loadr.min.js"></script>
<!-- OR -->
<script src="https://cdn.jsdelivr.net/npm/open-loadr/loadr.min.js"></script>

2. Add your image to the webpage. The src attribute will hold the URL of the low-resolution placeholder, while the hr-src attribute to your <img> tag. This attribute should contain the URL of your high-resolution image.

<img 
  hr-src="/path/to/high_res.jpg" 
  src="/path/to/low_res.png" />

3. Create a new Loadr instance in your JavaScript. That’s it!

new Loadr();

4. Customize the Loadr with the following options.

• async: Control how the library fetches high-resolution images. By default, it’s set to false, which means Loadr loads images synchronously. However, setting async to true enables asynchronous image loading.
• cache: If caching is enabled, Loadr checks if the high-resolution image is already in its cache. If it is, it directly swaps the placeholder with the cached image.
• delay: Control when the swap happens.

new Loadr({
  async: true,
  cache: true,
  delay: '1000' 
});

How Loadr Works:

• Initialization: When you create a Loadr instance, it searches for all elements with the hr-src attribute.
• Caching (Optional): If caching is enabled, Loadr checks if the high-resolution image is already in its cache. If it is, it directly swaps the placeholder with the cached image.
• Preloading: For images not in the cache, Loadr creates a new Image object and sets its src to the high-resolution image URL. This starts the image loading process in the background.
• Image Loaded Event: When the high-resolution image finishes loading, Loadr triggers a loadr:loaded event.
• Image Swapping: After an optional delay, Loadr replaces the src attribute of the element with the high-resolution image URL, effectively swapping the placeholder with the high-resolution image.
• Error Handling: If the high-resolution image fails to load, Loadr logs an error to the console.
• Cache Clearing: Loadr provides a clearCache() method to clear the image cache if needed.