How to Avoid Main-Thread Image Decode Jank

This guide is part of Image Decoding & Placeholders in Image & Media Optimization. Modern browsers decode most images off the main thread, on dedicated decoder or raster threads. But several common patterns pull decoding back onto the main thread or into the critical path of a frame: drawing images to canvas, inserting large images and painting them in the same frame, image-processing libraries running in JavaScript, and oversized images whose decode is too big to finish in the background before the frame needs it.

When that happens, the main thread is blocked for tens of milliseconds per image. During scrolling, frames are dropped; during interactions, the decode becomes part of processing or presentation delay and pushes INP past 200ms. On image-heavy experiences — galleries, maps, editors, social feeds — decode jank is often the dominant performance problem on mid-tier phones.

Rapid Diagnosis

• Find Image Decode events on the Main track in a throttled trace; their duration and the URL tell you which images.
• Check scroll performance. Record scrolling through image-heavy content with the frame track visible; dropped frames coinciding with image decodes confirm the issue.
• Check canvas code. Search for drawImage with freshly loaded images.
• Check client-side processing. Uploader previews, cropping tools and EXIF orientation fixes often run in JavaScript on the main thread.

Root Cause Analysis

1. Canvas drawImage before decode. The browser must decode synchronously to draw the pixels.

2. Oversized sources. A 4000px image displayed at 400px requires decoding 100x the needed pixels.

3. Bulk insertion. Inserting dozens of images at once (a grid page loaded by "load more") schedules many decodes simultaneously.

4. Main-thread image libraries. Resizing or filtering images in JavaScript blocks the thread for the whole operation.

Step-by-Step Resolution

1. Serve images at display size

Generate thumbnails and responsive sizes so decode work matches what is displayed — the single largest reduction, as covered in responsive images with srcset and sizes.

2. Decode off-thread for canvas and processing

// Decode off the main thread, then draw the bitmap (no sync decode).
const blob = await fetch(url).then((r) => r.blob());
const bitmap = await createImageBitmap(blob, { resizeWidth: 800, resizeQuality: 'high' });
ctx.drawImage(bitmap, 0, 0);
bitmap.close();
// trade-off: createImageBitmap with resize options produces a scaled bitmap;
// keep the original blob if you need full resolution later.

Expected outcome: canvas drawing no longer includes decode time on the main thread.

3. Move image processing into a worker

Use OffscreenCanvas and createImageBitmap in a Web Worker for resizing, cropping or filtering uploads, and transfer the result back.

// worker.js
self.onmessage = async ({ data: { blob, width } }) => {
  const bmp = await createImageBitmap(blob);
  const scale = width / bmp.width;
  const canvas = new OffscreenCanvas(width, Math.round(bmp.height * scale));
  canvas.getContext('2d').drawImage(bmp, 0, 0, canvas.width, canvas.height);
  const out = await canvas.convertToBlob({ type: 'image/webp', quality: 0.82 });
  self.postMessage(out);
};
// trade-off: OffscreenCanvas support is broad in modern browsers, but test the
// fallback path for older Safari versions if you support them.

4. Stagger bulk insertions

When appending many images, insert them in small batches across frames, with decoding="async", rather than all at once.

Verification

Re-record scrolling and the triggering interaction: Image Decode events should move off the Main track (or shrink to a few milliseconds), dropped frames should disappear, and the interaction's long tasks should be gone. In the field, INP for image-heavy interactions and LoAF render-phase durations on those views should improve.

Worked Example: An Image Upload Preview

A marketplace's listing form showed previews of uploaded photos (often 12-megapixel phone images) by reading them with FileReader, drawing them to a canvas to fix orientation and resize, and displaying the result. Each photo blocked the main thread for 300–600ms on mid-tier phones, and adding five photos made the form unresponsive for seconds. Moving decode and resize into a worker with createImageBitmap and OffscreenCanvas, and showing a skeleton until each preview was ready, removed the long tasks; INP for the form's interactions dropped from 640ms to 110ms.

Scrolling Image Feeds

Infinite feeds stress decoding continuously. Beyond right-sizing and async decoding, three practices keep them smooth: limit the number of images in the DOM by virtualising the list (off-screen images are removed and their bitmaps released); load the next batch's images slightly ahead of the viewport so decoding happens before they are needed; and avoid CSS effects (filters, large shadows) on every feed image, which add paint cost on top of decode. Measure with a scripted scroll in a throttled trace and count dropped frames before and after each change.

Common Mistakes

• Drawing freshly loaded images to canvas. Forces synchronous decode.
• Using full-resolution originals as thumbnails. Decode cost scales with source pixels.
• Processing uploads on the main thread. Blocks the UI for seconds on phones.
• Appending large batches at once. Concentrates decodes into one long frame.

Edge Cases

EXIF orientation. Modern browsers apply EXIF orientation automatically in <img> and createImageBitmap (with imageOrientation: 'from-image'), so manual canvas rotation is often unnecessary.

HEIC uploads. Many browsers cannot decode HEIC; server-side conversion avoids heavy JavaScript decoders.

WebGL textures. Uploading large textures stalls the GPU thread; use createImageBitmap and appropriately sized textures.

Memory limits. Decoding very large images can fail or crash tabs on low-memory devices; resize on the server whenever possible.

FAQ

Related

• Using decoding=async and the decode() API — the declarative controls.
• Transferring ArrayBuffers to workers without copying — moving image data cheaply.
• Virtualizing long lists in React — keeping image feeds' DOM small.