explaingit

desandro/imagesloaded

★ 8,871JavaScriptAudience · developerComplexity · 1/5LicenseSetup · easy

TLDR

imagesLoaded is a tiny JavaScript utility that fires a callback once all images inside a container have finished loading or failed, works with plain JS, jQuery, and supports CSS background images.

Mindmap

mindmap
  root((imagesLoaded))
    What it does
      Detect images ready
      Fire callback
      Track failures too
    Usage Modes
      Plain JavaScript
      jQuery plugin
      Background images
    Events
      done all loaded
      fail one broken
      always either way
      progress each image
    Install
      npm package
      CDN script tag
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Trigger a photo grid layout only after all images have loaded to prevent jumpy repositioning.

USE CASE 2

Start a CSS animation on a container only after every image inside it is fully ready.

USE CASE 3

Detect broken images in a page and replace each failed one with a placeholder fallback.

USE CASE 4

Watch CSS background images on a div finish loading before revealing the element.

Tech stack

JavaScriptjQuery

Getting it running

Difficulty · easy Time to first run · 5min
Use freely for any purpose, including commercial use, as long as you keep the copyright notice.

In plain English

imagesLoaded is a small JavaScript utility that tells you when all the images inside a container element have finished loading (or have failed to load). This is a common problem in web pages: you add images to the page, but the browser loads them in the background after the page structure is already drawn. If you want to do something (like lay out a photo grid or start an animation) only after the images are actually ready, you need a way to detect that moment. That is what this library does. You point it at a container element, and it watches every image inside. When all of them are either fully loaded or confirmed broken (an image that fails to download is still "done" in the sense that the browser is finished trying), it fires a callback function. You can also listen for progress events to react as each individual image finishes. The library works both with plain JavaScript and as a jQuery plugin. With plain JavaScript you call the function directly with an element, a CSS selector string, or a list of elements. With jQuery you call .imagesLoaded() on a jQuery selection. It also supports background images, not just img tags: passing a background option tells the library to watch for CSS background images on the container or on matching child elements. Events cover the main scenarios you would need: done (all images loaded successfully), fail (all done but at least one was broken), always (all done regardless of outcome), and progress (each image as it finishes). You can install it via npm or load it from a CDN. It works in Chrome, Firefox, Edge, and iOS Safari. The project is released under the MIT license.

Copy-paste prompts

Prompt 1
Write vanilla JavaScript using imagesLoaded to show a loading spinner until all images in a gallery container are ready.
Prompt 2
Use imagesLoaded with Masonry to initialize a photo grid layout only after all images have finished loading.
Prompt 3
Show me how to use imagesLoaded to catch individual broken images and swap in a placeholder src.
Prompt 4
Write jQuery code using .imagesLoaded() to fade in a photo grid once all images are loaded successfully.
Prompt 5
How do I use imagesLoaded with the background option to detect when a CSS background image has loaded on a div?
Open on GitHub → Explain another repo

← desandro on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.