imagesLoaded - Documentation

Introduction

What is imagesLoaded?

imagesLoaded is a small, fast, and robust JavaScript library that provides a callback mechanism once all images within a given container have fully loaded. This is particularly useful for situations where you need to perform actions (like resizing a layout, revealing hidden content, or triggering animations) that depend on image dimensions being available. Unlike simply checking for onload on each image, imagesLoaded accounts for images that fail to load and handles image caching effectively.

Why use imagesLoaded?

Using imagesLoaded offers several key advantages:

Installation and Setup

imagesLoaded is available via npm and yarn. You can also include it directly via a CDN.

Using npm or yarn:

npm install imagesloaded
# or
yarn add imagesloaded

Then, import it into your JavaScript file:

import imagesLoaded from 'imagesloaded';

Using a CDN (e.g., jsDelivr):

Include the following <script> tag in the <head> of your HTML file:

<script src="https://cdn.jsdelivr.net/npm/imagesloaded@5/imagesloaded.pkgd.min.js"></script>

Basic Usage Example

This example shows how to use imagesLoaded to wait for all images within a container with the ID “my-images” to load before displaying a message.

import imagesLoaded from 'imagesloaded';

const imageContainer = document.getElementById('my-images');

imagesLoaded(imageContainer, function() {
  console.log('All images loaded!');
  // Perform actions that depend on image dimensions here, e.g.,
  document.getElementById('loading-message').style.display = 'none';
});

Remember to include the imagesloaded.js file (either via npm/yarn or CDN) before this JavaScript code in your HTML. This example utilizes an element with the ID “loading-message” that will be hidden after all images have loaded. Replace this with your own logic as needed. The imageContainer can be any DOM element containing images. It doesn’t have to be a <div>. It could even be the <body> element itself if you want to wait for all images on the page to load.

Core Functionality

Loading Images

The core functionality of imagesLoaded centers around the imagesLoaded function. This function takes a DOM element as its first argument (the container element containing images) and a callback function as its second. The callback function is executed only after all images within the container have fully loaded.

The imagesLoaded function intelligently handles various scenarios:

Event Handling (progress, done, fail)

The imagesLoaded function, while primarily using a callback, also offers a more flexible approach using events. This allows for finer-grained control over the loading process.

Instead of directly passing a callback function to imagesLoaded, you can create an instance of the imagesLoaded class and then listen for events. This provides more sophisticated control over event handling. The events emitted are:

Here’s an example using the event-based approach:

import imagesLoaded from 'imagesloaded';

const imageContainer = document.getElementById('my-images');

const instance = imagesLoaded(imageContainer);

instance.on( 'progress', function( instance, image ) {
  console.log( 'image loaded:', image.img );
});

instance.on( 'done', function() {
  console.log( 'All images loaded!' );
});

instance.on( 'fail', function( instance, image ) {
  console.log( 'Image failed to load:', image.img.src);
});

Handling Different Image Types

imagesLoaded inherently supports various image formats without any additional configuration. It correctly identifies and handles the loading of JPEG, PNG, GIF, SVG, and other common image types. You don’t need to perform any special checks or pre-processing for different image formats.

Debugging and Troubleshooting

If you are still experiencing issues, please provide details including your code, the browser you are using, and the specific error message (if any) for more targeted assistance.

Advanced Usage

Using imagesLoaded with Frameworks (React, Angular, Vue)

While imagesLoaded is a vanilla JavaScript library, integrating it into popular frameworks like React, Angular, and Vue is straightforward. The core principle remains the same: you need to select the container element and then use the imagesLoaded function or event system. However, the specifics of how you select the element and handle the callback will depend on the framework.

React:

import React, { useEffect, useState } from 'react';
import imagesLoaded from 'imagesloaded';

function MyComponent() {
  const [imagesLoadedStatus, setImagesLoadedStatus] = useState(false);
  const imageContainerRef = useRef(null);

  useEffect(() => {
    if (imageContainerRef.current) {
      imagesLoaded(imageContainerRef.current).on('done', () => {
        setImagesLoadedStatus(true);
      });
    }
  }, []);

  return (
    <div ref={imageContainerRef}>
      {/* Your images here */}
      {imagesLoadedStatus && <p>All images loaded!</p>}
    </div>
  );
}

Angular:

You can use ViewChild or ElementRef to access the container element within your Angular component, and then call imagesLoaded within ngOnInit or a similar lifecycle hook.

Vue:

You can use a ref to access the container element in your Vue template and then call imagesLoaded within a mounted lifecycle hook or a watcher.

In all these framework examples, the crucial part is ensuring that the imagesLoaded call is made after the DOM element containing the images has been rendered. Framework-specific lifecycle hooks or asynchronous operations (like useEffect in React) are essential for proper timing.

Customizing the Loading Process

While imagesLoaded automatically handles most scenarios, you can customize certain aspects:

Working with Background Images

imagesLoaded primarily focuses on images that are directly part of the DOM (<img> tags). To handle background images, you’ll need a different approach, as imagesLoaded does not directly detect the loading of background images. Consider using the onload event listener on a hidden <img> tag that points to the background image URL to track when the background image has fully loaded.

Handling Large Numbers of Images

For exceptionally large numbers of images, optimizing the loading process becomes crucial. Consider these strategies:

Performance Optimization

Beyond the strategies already mentioned for large numbers of images, other general performance improvements apply to imagesLoaded usage:

Remember to profile your application to identify specific performance bottlenecks. Using browser developer tools is key to pinpointing areas for optimization.

API Reference

imagesLoaded(elements, options)

The core function of the imagesLoaded library. It takes two arguments:

Return Value:

The function returns an imagesLoaded instance. This object allows you to listen for events (progress, done, fail) using the .on() method. In older versions a simple callback was provided as the second argument. The newer event system provides more flexibility.

Example:

import imagesLoaded from 'imagesloaded';

const myContainer = document.querySelector('.my-image-container');
const imgArray = [document.getElementById('image1'), document.getElementById('image2')];

// Using a single element
const instance1 = imagesLoaded( myContainer );
instance1.on('done', () => console.log('All images in myContainer loaded!') );

// Using an array of elements
const instance2 = imagesLoaded( imgArray );
instance2.on('done', () => console.log('All images in the array loaded!') );

// Using a selector string
const instance3 = imagesLoaded( '.my-other-images' );
instance3.on('done', () => console.log('All images in elements with the class my-other-images loaded!') );

Event Handlers

The imagesLoaded instance returned by the imagesLoaded() function exposes the .on() method to attach event listeners. Available events are:

Example using .on():

const instance = imagesLoaded(myContainer);

instance.on( 'progress', (instance, image) => {
  console.log(`Image loaded: ${image.img.src}`);
} );

instance.on( 'done', () => {
  console.log('All images loaded!');
} );

instance.on( 'fail', (instance, image) => {
  console.log(`Image failed to load: ${image.img.src}`);
} );

Options Object

The options object (second argument to imagesLoaded()) allows for fine-grained control over the loading process. While not all options are available in all versions, and newer options might have replaced older ones, the following are representative:

It’s crucial to consult the most up-to-date documentation for the specific version of imagesLoaded you are using, as the API and available options may have changed over time. The options listed here are illustrative examples and may not represent all options available in all versions.

Contributing

We welcome contributions to imagesLoaded! Whether you’re reporting a bug, suggesting a feature, or submitting a pull request, your involvement is valuable.

Reporting Issues

Before creating a new issue, please search existing issues to see if the problem has already been reported. If you can’t find a matching issue, please create a new one providing the following information:

Submitting Pull Requests

If you’d like to contribute code, follow these steps:

  1. Fork the repository: Create a fork of the official imagesLoaded repository on GitHub.
  2. Create a new branch: Create a new branch for your changes. Use descriptive branch names (e.g., fix-bug-123, feature-new-option).
  3. Make your changes: Implement your changes, following the coding style guide (described below).
  4. Test your changes thoroughly: Ensure your changes work correctly and don’t introduce new bugs.
  5. Commit your changes: Commit your changes with clear and concise commit messages.
  6. Push your branch: Push your branch to your forked repository.
  7. Create a pull request: Create a pull request on the original imagesLoaded repository, clearly describing your changes and their purpose.

Coding Style Guide

To maintain consistency and readability, please adhere to the following coding style guidelines when contributing to imagesLoaded:

We use ESLint to enforce code style. It’s recommended to install ESLint and configure it according to the project’s .eslintrc file before submitting a pull request. This will help you identify and fix style issues before they are submitted. The project maintainers might reject pull requests that do not follow the styling guide.