The ImageDecoder API is a modern web API that gives developers low-level control over image decoding. Unlike the <img> tag which handles decoding automatically in a black-box manner, ImageDecoder allows you to decode images frame-by-frame, track decoding progress, extract detailed metadata, and even perform progressive decoding where partial image data yields a preview before the full image loads. It's part of the WebCodecs family of APIs, designed for high-performance media processing directly in the browser.

Progressive decoding allows an image to be displayed at increasing levels of quality as the data streams in, rather than waiting for the entire file to download. This is especially valuable for large images on slow connections — users see a blurry preview almost immediately, which sharpens as more data arrives. The ImageDecoder API enables this by setting completeFramesOnly: false during decode, returning partial frames that can be rendered right away. This technique dramatically improves perceived performance and user experience.

The ImageDecoder API supports all major web image formats: JPEG, PNG, WebP (both static and animated), AVIF (static and animated), GIF, BMP, and ICO. Support may vary slightly by browser — Chrome 94+ offers the broadest support. For animated formats like animated WebP and AVIF, ImageDecoder gives you frame-level access that's simply not available with standard <img> elements.

Feature	<img> Tag	ImageDecoder API
Automatic decoding	✅ Yes	❌ Manual control
Progressive rendering	⚠ Browser-dependent	✅ Full control
Frame-level access	❌ Not available	✅ Every frame accessible
Metadata before decode	❌ Must load fully	✅ Available via tracks
Decode progress tracking	❌ Limited	✅ Real-time progress
Memory efficiency	⚠ Automatic	✅ Selective frame decoding

The ImageDecoder API excels when you need fine-grained control — for image editors, animation tools, performance-critical applications, or any scenario where understanding exactly what's happening during decode matters.

As of 2024, the ImageDecoder API is supported in Google Chrome 94+, Microsoft Edge 94+, and other Chromium-based browsers. Safari and Firefox have not yet implemented the API, though it's being discussed in standards groups. For production sites, always feature-detect using 'ImageDecoder' in window and provide a fallback (such as using <img> or createImageBitmap). This demo tool includes automatic detection and will warn you if your browser lacks support.

Absolutely! This is one of the ImageDecoder API's killer features. For animated GIFs, WebP, and AVIF files, you can access each frame individually via decode({frameIndex: n}). Each decoded VideoFrame includes timing information, so you can precisely control playback speed, jump to specific frames, or even extract individual frames as still images. The API also exposes the total frame count via tracks[0].frameCount — use our frame strip viewer above to browse through every frame of an animated image interactively.

• Image editors — Load and manipulate images at the pixel level with full decode control.
• Animation tools — Inspect, edit, and re-export individual frames of animated images.
• Progressive image viewers — Show images that sharpen as they load, improving UX on slow networks.
• Performance-critical apps — Decode only the frames or resolution levels needed, saving memory.
• Image format converters — Read any supported format via ImageDecoder, then re-encode with canvas or WebCodecs.
• Lazy-loading implementations — Fetch metadata first, then decide whether to fully decode based on viewport visibility.

Use a simple feature detection check:

if ('ImageDecoder' in window) {
  // ImageDecoder API is available
  const decoder = new ImageDecoder({type: 'file', data: arrayBuffer});
  const result = await decoder.decode({frameIndex: 0});
  // ... use result.image (a VideoFrame)
} else {
  // Fallback: use createImageBitmap or <img> tag
  const bitmap = await createImageBitmap(blob);
}

This demo tool runs this check automatically on page load and displays the API status badge at the top of the page.

When using ImageDecoder, you're getting raw decoded pixel data without any browser post-processing (like color profile adjustments or orientation correction). The <img> tag automatically applies EXIF orientation, color space conversions, and other corrections. With ImageDecoder, you're responsible for handling these yourself if needed. This is actually an advantage for applications that need pixel-perfect, unmodified image data. Check the tracks metadata for color space information that can guide your rendering.

When you enable "Simulate Progressive Load", the demo applies a CSS blur filter to the canvas that gradually decreases over ~2.5 seconds, visually mimicking the experience of a progressive image load. While this is a visual simulation, the real ImageDecoder API achieves actual progressive decoding when paired with a ReadableStream — as data chunks arrive over the network, the decoder can produce increasingly complete frames that naturally transition from blurry to sharp. For a true progressive decode demo, try loading a large image via URL with the "Complete Frames Only" option disabled.