Front-end apps often need to know exactly when an image is ready so you can swap placeholders, start animations, or measure layout. It sounds simple until you hit race conditions, browser caching, or background images. <\/p>\n\n\n\n
I need to show a loader until my images are fully ready on the page. What is the most reliable way to detect image load success and failure in the browser? Specifically, how to check if an image has loaded in JavaScript? I want something that works both for existing tags and for programmatically created images, plus a safe approach for CSS background images. Any best practices for cached images or lazy loading would be appreciated.<\/em><\/p>\n\n\n\n The short version: listen for the If an image is already cached, the Background images do not emit load events. Preload with an Combine IntersectionObserver with the patterns above to defer loading until the image is visible.<\/p>\n\n\n After you have the generic pattern in place, Cloudinary can help you deliver faster and safer. For example, serve optimized formats and quality automatically, which reduces load time variance:<\/p>\n\n\n Apply the lazy loading snippet above to replace Answer:<\/h2>\n\n\n\n
load<\/code> and error<\/code> events, use the complete<\/code> and naturalWidth<\/code> properties for already-cached images, and consider HTMLImageElement.decode()<\/code> when you care about paint timing.<\/p>\n\n\n\n1) Existing
<img><\/code> in the DOM<\/h3>\n\n\nconst<\/span> img = document<\/span>.querySelector('img.hero'<\/span>);\n\nfunction<\/span> onReady<\/span>(<\/span>) <\/span>{\n\u00a0 console<\/span>.log('Image loaded and has dimensions:'<\/span>, img.naturalWidth, img.naturalHeight);\n}\n\nfunction<\/span> onFail<\/span>(<\/span>) <\/span>{\n\u00a0 console<\/span>.error('Image failed to load:'<\/span>, img.src);\n}\n\n\/\/ If the image may already be cached<\/span>\nif<\/span> (img.complete && img.naturalWidth !== 0<\/span>) {\n\u00a0 onReady();\n} else<\/span> {\n\u00a0 img.addEventListener('load'<\/span>, onReady, { once<\/span>: true<\/span> });\n\u00a0 img.addEventListener('error'<\/span>, onFail, { once<\/span>: true<\/span> });\n}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n\n
img.complete<\/code> is true once the fetch has finished.<\/li>\n\n\n\nimg.naturalWidth<\/code> lets you differentiate between a cached error and a real image.<\/li>\n<\/ul>\n\n\n\n2) Programmatically loading an image URL<\/h3>\n\n\n
function<\/span> loadImage<\/span>(url, { timeout = 10000<\/span> } = {}<\/span>) <\/span>{\n\u00a0 return<\/span> new<\/span> Promise<\/span>((resolve, reject<\/span>) =><\/span> {\n\u00a0 \u00a0 const<\/span> img = new<\/span> Image();\n\u00a0 \u00a0 const<\/span> t = setTimeout(()<\/span> =><\/span> {\n\u00a0 \u00a0 \u00a0 img.src = ''<\/span>; \/\/ Stop downloading<\/span>\n\u00a0 \u00a0 \u00a0 reject(new<\/span> Error<\/span>('Image load timed out'<\/span>));\n\u00a0 \u00a0 }, timeout);\n\n\u00a0 \u00a0 img.onload = ()<\/span> =><\/span> {\n\u00a0 \u00a0 \u00a0 clearTimeout(t);\n\u00a0 \u00a0 \u00a0 resolve(img);\n\u00a0 \u00a0 };\n\u00a0 \u00a0 img.onerror = ()<\/span> =><\/span> {\n\u00a0 \u00a0 \u00a0 clearTimeout(t);\n\u00a0 \u00a0 \u00a0 reject(new<\/span> Error<\/span>('Image failed to load'<\/span>));\n\u00a0 \u00a0 };\n\u00a0 \u00a0 img.src = url;\n\u00a0 });\n}\n\n\/\/ Usage<\/span>\nloadImage('\/images\/hero@2x.jpg'<\/span>)\n\u00a0 .then(img<\/span> =><\/span> document<\/span>.body.appendChild(img))\n\u00a0 .catch(console<\/span>.error);<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n3) Ensuring it is decoded and ready to paint<\/h3>\n\n\n\n
load<\/code> event can fire before the browser decodes it for painting. Use img.decode()<\/code> for an extra guarantee.<\/p>\n\n\nasync<\/span> function<\/span> whenPaintReady<\/span>(img<\/span>) <\/span>{\n\u00a0 if<\/span> (img.complete && img.naturalWidth !== 0<\/span>) {\n\u00a0 \u00a0 try<\/span> { await<\/span> img.decode(); } catch<\/span> { \/* decode may reject on some errors *\/<\/span> }\n\u00a0 \u00a0 return<\/span> img;\n\u00a0 }\n\u00a0 await<\/span> new<\/span> Promise<\/span>((res, rej<\/span>) =><\/span> {\n\u00a0 \u00a0 img.addEventListener('load'<\/span>, res, { once<\/span>: true<\/span> });\n\u00a0 \u00a0 img.addEventListener('error'<\/span>, rej, { once<\/span>: true<\/span> });\n\u00a0 });\n\u00a0 try<\/span> { await<\/span> img.decode(); } catch<\/span> {}\n\u00a0 return<\/span> img;\n}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n4) CSS background images<\/h3>\n\n\n\n
Image()<\/code> object, then apply the background once ready.<\/p>\n\n\nfunction<\/span> preloadBackground<\/span>(url<\/span>) <\/span>{\n\u00a0 return<\/span> loadImage(url).then(()<\/span> =><\/span> url);\n}\n\npreloadBackground('\/images\/bg.jpg'<\/span>)\n\u00a0 .then(url<\/span> =><\/span> {\n\u00a0 \u00a0 document<\/span>.querySelector('.hero'<\/span>).style.backgroundImage = `url(\"${url}<\/span>\")`<\/span>;\n\u00a0 })\n\u00a0 .catch(console<\/span>.error);<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n5) Lazy loading and viewport observers<\/h3>\n\n\n\n
const<\/span> io = new<\/span> IntersectionObserver(entries<\/span> =><\/span> {\n\u00a0 for<\/span> (const<\/span> e of<\/span> entries) {\n\u00a0 \u00a0 if<\/span> (e.isIntersecting) {\n\u00a0 \u00a0 \u00a0 const<\/span> img = e.target;\n\u00a0 \u00a0 \u00a0 img.src = img.dataset.src;\n\u00a0 \u00a0 \u00a0 whenPaintReady(img).then(()<\/span> =><\/span> {\n\u00a0 \u00a0 \u00a0 \u00a0 img.classList.add('is-ready'<\/span>);\n\u00a0 \u00a0 \u00a0 });\n\u00a0 \u00a0 \u00a0 io.unobserve(img);\n\u00a0 \u00a0 }\n\u00a0 }\n});\n\ndocument<\/span>.querySelectorAll('img[data-src]'<\/span>).forEach(img<\/span> =><\/span> io.observe(img));<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n6) Handling caches and servers<\/h3>\n\n\n\n
\n
load<\/code> fire immediately. Check complete<\/code> first.<\/li>\n\n\n\nOptional: Make this easier with Cloudinary<\/h3>\n\n\n\n
<img\n\u00a0 class<\/span><\/span>=\"hero\"<\/span>\n\u00a0 alt=\"Sample\"<\/span>\n\u00a0 src=\"https:\/\/res.cloudinary.com\/demo\/image\/upload\/f_auto,q_auto,w_1200\/sample.jpg\"<\/span>\n\/>\n\nYou can also bootstrap a blurred placeholder, then swap to the full image once your onload logic fires:\n\n<img<\/span>\n\u00a0 class<\/span>=\"hero\"<\/span>\n\u00a0 alt<\/span>=\"Sample\"<\/span>\n\u00a0 src<\/span>=\"https:\/\/res.cloudinary.com\/demo\/image\/upload\/w_24,e_blur:2000,q_auto,f_auto\/sample.jpg\"<\/span>\n\u00a0 data-src<\/span>=\"https:\/\/res.cloudinary.com\/demo\/image\/upload\/f_auto,q_auto,w_1200\/sample.jpg\"<\/span>\n\/><\/span><\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\nsrc<\/code> with data-src<\/code> on intersection. This improves real-world performance for your media assets<\/a> without complicating your code structure.<\/p>\n\n\n\nTL;DR<\/h2>\n\n\n\n
\n
img.complete<\/code> and naturalWidth<\/code> first, then attach load<\/code> and error<\/code> listeners.<\/li>\n\n\n\nimg.decode()<\/code> when you need paint-ready assurance.<\/li>\n\n\n\nImage()<\/code> and then set background-image<\/code>.<\/li>\n\n\n\nf_auto<\/code> and q_auto<\/code> to speed up perceived load.<\/li>\n<\/ul>\n\n\n\nLearn More<\/h2>\n\n\n\n