Image Gallery with Lightbox

A gallery may start with six images, but it should not be built as six unrelated blocks of HTML. A common mistake is copying and pasting the same image markup again and again. This makes the gallery hard to update, because every image has its own manually written thumbnail, full-size image, alt text, caption, and lightbox content. If you later add filtering, categories, captions, or next/previous navigation, duplicated markup becomes difficult to maintain.

A better approach is to define image data first. Each image should have a stable ID, thumbnail source, full-size source, alt text, caption, and optional category or external link. Then the gallery can render items from that data. This keeps the HTML consistent and makes the lightbox easier to control because the selected image always comes from one predictable source.

Problematic approach:

          <div class="gallery">
            <img src="/img/photo-1.jpg" onclick="openLightbox('img/photo-1.jpg')" />
            <img src="/img/photo-2.jpg" onclick="openLightbox('img/photo-2.jpg')" />
            <img src="/img/photo-3.jpg" onclick="openLightbox('img/photo-3.jpg')" />
          </div>

This works only for a very small demo. The images have no useful alt text, the click logic is mixed into HTML, and there is no structured way to store captions or full-size image paths.

Better data model:

          const galleryImages = [
            {
              id: "mountain-lake",
              thumbnailSrc: "images/thumbs/mountain-lake.jpg",
              fullSrc: "images/full/mountain-lake.jpg",
              alt: "Mountain lake surrounded by trees",
              caption: "Morning view near the mountain lake",
              category: "Nature"
            },
            {
              id: "city-street",
              thumbnailSrc: "images/thumbs/city-street.jpg",
              fullSrc: "images/full/city-street.jpg",
              alt: "Evening city street with lights",
              caption: "City lights after sunset",
              category: "Urban"
            }
          ];

Rendering from data:

          function renderGallery(images) {
            const gallery = document.querySelector("[data-gallery]");

            gallery.innerHTML = images
              .map((image) => {
                return `
                  <button
                    class="gallery__item"
                    type="button"
                    data-image-id="${image.id}"
                    aria-label="Open image: ${image.alt}"
                  >
                    <img
                      src="/${image.thumbnailSrc}"
                      alt="${image.alt}"
                      loading="lazy"
                    />
                  </button>
                `;
              })
              .join("");
          }

Pay attention to: A gallery needs structured image data. Store thumbnails, full-size images, captions, alt text, and IDs in one place instead of scattering them through duplicated markup.

A lightbox is not just a large image on top of the page. It behaves like a modal dialog, which means users need a clear way to close it, keyboard focus should move into the lightbox, and screen readers should understand that a new dialog is open. A common beginner mistake is showing an overlay visually but leaving the rest of the page active behind it.

This creates several usability problems. Keyboard users may tab into links behind the overlay. Screen-reader users may not know that the lightbox opened. Mobile users may accidentally scroll the page behind the modal. A polished Image Gallery with Lightbox should handle open, close, Escape key, focus, and overlay behavior intentionally.

Problematic approach:

          <div class="lightbox">
            <img src="/images/full/mountain-lake.jpg" />
          </div>

This shows a large image, but it does not identify the overlay as a dialog, does not include a close button, and does not provide image alt text.

Better lightbox structure:

          <div
            class="lightbox"
            data-lightbox
            role="dialog"
            aria-modal="true"
            aria-labelledby="lightbox-title"
            hidden
          >
            <div class="lightbox__backdrop" data-lightbox-close></div>

            <div class="lightbox__panel">
              <button
                class="lightbox__close"
                type="button"
                data-lightbox-close
                aria-label="Close image preview"
              >
                ×
              </button>

              <h2 id="lightbox-title" class="sr-only">Image preview</h2>

              <img data-lightbox-image src="/" alt="" />

              <p class="lightbox__caption" data-lightbox-caption></p>
            </div>
          </div>

Open and close logic:

          const lightbox = document.querySelector("[data-lightbox]");
          const lightboxImage = document.querySelector("[data-lightbox-image]");
          const lightboxCaption = document.querySelector("[data-lightbox-caption]");
          const closeButtons = document.querySelectorAll("[data-lightbox-close]");

          function openLightbox(image) {
            lightboxImage.src = image.fullSrc;
            lightboxImage.alt = image.alt;
            lightboxCaption.textContent = image.caption;

            lightbox.hidden = false;
            document.body.classList.add("is-lightbox-open");

            const closeButton = lightbox.querySelector(".lightbox__close");
            closeButton.focus();
          }

          function closeLightbox() {
            lightbox.hidden = true;
            lightboxImage.src = "";
            lightboxImage.alt = "";
            document.body.classList.remove("is-lightbox-open");
          }

          closeButtons.forEach((button) => {
            button.addEventListener("click", closeLightbox);
          });

          document.addEventListener("keydown", (event) => {
            if (event.key === "Escape" && !lightbox.hidden) {
              closeLightbox();
            }
          });

Pay attention to: A lightbox should behave like a modal, not only look like one. Add dialog semantics, close controls, Escape key support, focus handling, and body-scroll control.

Lightbox navigation usually needs previous and next buttons. The common mistake is incrementing or decrementing an image index without checking boundaries. This can produce undefined images, broken sources, or buttons that continue working even when there is no next image. The problem becomes worse when galleries are filtered, reordered, or generated dynamically.

A stronger approach is to keep a selected image ID or selected index that is always derived from the current gallery array. Navigation should wrap safely or disable buttons at the beginning and end. The important part is consistency: users should never click “Next” and see a broken image.

Problematic approach:

          let selectedIndex = 0;

          function showNextImage() {
            selectedIndex += 1;

            lightboxImage.src = galleryImages[selectedIndex].fullSrc;
          }

          function showPreviousImage() {
            selectedIndex -= 1;

            lightboxImage.src = galleryImages[selectedIndex].fullSrc;
          }

This code can easily move outside the image array. It also does not update the caption or alt text together with the image.

Better selected image state:

          let selectedImageId = null;

          function getSelectedImageIndex() {
            return galleryImages.findIndex((image) => {
              return image.id === selectedImageId;
            });
          }

          function setSelectedImage(image) {
            selectedImageId = image.id;

            lightboxImage.src = image.fullSrc;
            lightboxImage.alt = image.alt;
            lightboxCaption.textContent = image.caption;
          }

Safe wrap-around navigation:

          function showNextImage() {
            const currentIndex = getSelectedImageIndex();

            if (currentIndex === -1) {
              setSelectedImage(galleryImages[0]);
              return;
            }

            const nextIndex = (currentIndex + 1) % galleryImages.length;

            setSelectedImage(galleryImages[nextIndex]);
          }

          function showPreviousImage() {
            const currentIndex = getSelectedImageIndex();

            if (currentIndex === -1) {
              setSelectedImage(galleryImages[0]);
              return;
            }

            const previousIndex =
              (currentIndex - 1 + galleryImages.length) % galleryImages.length;

            setSelectedImage(galleryImages[previousIndex]);
          }

Keyboard navigation:

          document.addEventListener("keydown", (event) => {
            if (lightbox.hidden) {
              return;
            }

            if (event.key === "ArrowRight") {
              showNextImage();
            }

            if (event.key === "ArrowLeft") {
              showPreviousImage();
            }
          });

Pay attention to: Next and previous buttons must always update the image, caption, and alt text together. Handle array boundaries and keyboard navigation intentionally.

Image galleries can become heavy very quickly. If every thumbnail loads a full-size image, the page becomes slow even before the user opens the lightbox. A beginner gallery may look fine with four small demo images, but a real gallery with twelve or twenty high-resolution images can hurt loading speed and mobile performance.

A better implementation separates thumbnail images from full-size images. The gallery grid should load smaller thumbnails, and the lightbox should load the larger version only when the user opens it. Add loading="lazy", define image dimensions or aspect ratio, and use object-fit: cover so the layout does not jump while images load.

Problematic approach:

          <img
            src="/images/full/large-photo-1.jpg"
            alt="Forest path"
          />

          <img
            src="/images/full/large-photo-2.jpg"
            alt="City skyline"
          />

This loads full-size images directly in the gallery grid. The user pays the performance cost even if they never open the lightbox.

Better thumbnail markup:

          <button
            class="gallery__item"
            type="button"
            data-image-id="forest-path"
          >
            <img
              src="/images/thumbs/forest-path.jpg"
              alt="Forest path in soft morning light"
              width="480"
              height="320"
              loading="lazy"
            />
          </button>

Responsive CSS Grid:

          .gallery {
            display: grid;
            grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
            gap: 16px;
          }

          .gallery__item {
            border: 0;
            padding: 0;
            border-radius: 16px;
            overflow: hidden;
            cursor: pointer;
            background: transparent;
          }

          .gallery__item img {
            width: 100%;
            aspect-ratio: 4 / 3;
            display: block;
            object-fit: cover;
            transition: transform 180ms ease;
          }

          .gallery__item:hover img,
          .gallery__item:focus-visible img {
            transform: scale(1.04);
          }

Lightbox image:

          .lightbox__panel img {
            max-width: min(92vw, 1100px);
            max-height: 78vh;
            width: auto;
            height: auto;
            object-fit: contain;
          }

Pay attention to: Use thumbnails in the grid and full-size images in the lightbox. Add lazy loading, stable dimensions, responsive grid sizing, and object-fit rules to protect performance and layout stability.

Image galleries often become visually attractive but informationally weak. A common mistake is using empty alt attributes for every image or repeating the same generic phrase such as “gallery image.” If the image is meaningful, the alt text should describe it. If the gallery includes captions, the lightbox should update the caption when the selected image changes.

Captions also help sighted users understand the image. For example, a portfolio gallery may need project names, locations, client categories, or short descriptions. A travel gallery may need place names. A product gallery may need angle descriptions. Without this context, the lightbox becomes only a bigger picture, not a better viewing experience.

Problematic approach:

          <img src="/images/photo-1.jpg" alt="image" />
          <img src="/images/photo-2.jpg" alt="image" />
          <img src="/images/photo-3.jpg" alt="image" />

This alt text does not help users understand what each image shows.

Better image data:

          const galleryImages = [
            {
              id: "old-town",
              thumbnailSrc: "images/thumbs/old-town.jpg",
              fullSrc: "images/full/old-town.jpg",
              alt: "Narrow street in an old European town",
              caption: "Old town street photographed during golden hour"
            },
            {
              id: "desert-road",
              thumbnailSrc: "images/thumbs/desert-road.jpg",
              fullSrc: "images/full/desert-road.jpg",
              alt: "Empty road crossing a desert landscape",
              caption: "Desert road with mountains in the distance"
            }
          ];

Caption update:

          function updateLightboxContent(image) {
            lightboxImage.src = image.fullSrc;
            lightboxImage.alt = image.alt;
            lightboxCaption.textContent = image.caption;
          }

Optional image counter:

          function updateImageCounter() {
            const currentIndex = getSelectedImageIndex();

            imageCounter.textContent = `${currentIndex + 1} of ${galleryImages.length}`;
          }

Pay attention to: Every meaningful image needs useful alt text. Captions, counters, and descriptions make the lightbox more understandable and more professional.

Using a lightbox library can be a good decision, especially if the gallery needs video support, captions, thumbnails, transitions, mobile gestures, or plugin extensions. The mistake is installing a plugin and treating it as magic. If you do not understand its required markup, initialization, cleanup, and configuration, the gallery may work in one demo but become hard to debug in a real project.

Plugin-based galleries are especially useful when the project includes mixed media such as images and videos. But for a beginner or intermediate portfolio project, you should still understand the basics: which element initializes the gallery, which attributes define full media sources, how captions are passed, and how the plugin behaves on mobile.

Problematic approach:

          lightGallery(document.querySelector(".gallery"));

This may initialize the plugin, but the project does not document what features are enabled, what markup the plugin expects, or how video/caption behavior works.

Better plugin markup:

          <div class="gallery-container" id="gallery-container">
            <a
              href="/images/full/mountain-lake.jpg"
              data-src="images/full/mountain-lake.jpg"
              data-sub-html="<h4>Mountain Lake</h4><p>Morning view near the lake.</p>"
            >
              <img
                src="/images/thumbs/mountain-lake.jpg"
                alt="Mountain lake surrounded by trees"
              />
            </a>
          </div>

Clear initialization:

          const galleryContainer = document.getElementById("gallery-container");

          if (galleryContainer) {
            lightGallery(galleryContainer, {
              speed: 500,
              selector: "a",
              download: false
            });
          }

Document what the plugin handles:

          /*
            Plugin handles:
            - opening and closing the lightbox
            - slide transitions
            - mobile gestures
            - media captions

            Project still controls:
            - image data quality
            - thumbnail performance
            - alt text
            - layout and responsive grid
          */

Pay attention to: A plugin can save time, but it does not replace understanding. Know which features the library handles and which responsibilities still belong to your own gallery code.