Skip to content
Shubham JangleResources
Browser performance

Explore topics

Image Optimization & Custom Image Rendering

Watch the walkthrough
Open on Instagram

Quick revision

Optimize image bytes, discovery, decoding, and layout stability together. Serve images sized for the rendered slot, use efficient formats where suitable, and give the browser width/height or an aspect ratio before the image arrives. Responsive srcset and sizes prevent downloading a desktop-sized asset for a small viewport.

Use native loading="lazy" for offscreen images. Keep the likely Largest Contentful Paint image eagerly discoverable; lazy-loading it can delay the most important content. Use fetch priority selectively for that primary image, not every gallery item.

Read the copied gallery

Each record contains a small thumbnail and a full-resolution image. The wrapper reserves space; the full image's onLoad toggles opacity and reveals it. Both requests are lazy. The thumbnail makes loading look smoother, but downloading two versions is not automatically a bandwidth reduction. The source still needs its public numbered image assets, and it has no error state or reset when sources change.

Revision checks

Throttle the network and compare request sizes, LCP, and layout shifts. Check failed image loads and meaningful alternative text. Decorative placeholder images should not duplicate the accessible description of the final image.

Reference: Browser image lazy loading. Related theory: Browser performance revision.

Original repository source

These are the supplied checkout's React 18/Vite examples. Code is preserved apart from line endings; revision recommendations above are separate. Use the original project dependencies and configuration when running them.

Gallery.tsx

Original file on GitHub

import { useState } from "react";

const ImageGallery = () => {
  const imageCount = 20;
  const images = Array.from({ length: imageCount }, (_, index) => {
    const number = index + 1;
    return {
      full: `/${number}.jpg`,
      thumbnail: `/${number}-small.jpg`,
    };
  });

  return (
    <div className="container mx-auto px-4 py-4">
      <h1 className="text-2xl font-bold mb-6 text-center">Image Gallery</h1>
      <div className="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4">
        {images.map((src, index) => (
          <div
            key={index}
            className="relative overflow-hidden rounded-lg bg-gray-200"
          >
            {/* <img
              src={src.full}
              alt={`Gallery image ${index + 1}`}
              loading="lazy"
              className="w-full h-96 object-cover"
            /> */}
            <ProgressiveImage
              fullSrc={src.full}
              thumbnailSrc={src.thumbnail}
              alt={`Gallery image ${index + 1}`}
            />
          </div>
        ))}
      </div>
    </div>
  );
};

export default ImageGallery;

interface ProgressiveImageProps {
  fullSrc: string;
  thumbnailSrc: string;
  alt: string;
}

const ProgressiveImage: React.FC<ProgressiveImageProps> = ({
  fullSrc,
  thumbnailSrc,
  alt,
}) => {
  const [imageLoaded, setImageLoaded] = useState(false);

  return (
    <div className="relative w-full pb-[150%]">
      {/* Thumbnail (always visible initially) */}
      <img
        src={thumbnailSrc}
        alt={`${alt} thumbnail`}
        loading="lazy"
        className={`
            absolute top-0 left-0 w-full h-full 
            object-cover 
            transition-opacity duration-300
            ${imageLoaded ? "opacity-0" : "opacity-100"}
          `}
      />
      {/* Full resolution image */}
      <img
        src={fullSrc}
        alt={alt}
        loading="lazy"
        onLoad={() => setImageLoaded(true)}
        className={`
            absolute top-0 left-0 w-full h-full 
            object-cover 
            transition-opacity duration-300
            ${imageLoaded ? "opacity-100" : "opacity-0"}
          `}
      />
    </div>
  );
};