Image Gallery Grid

A common mistake in image gallery projects is defining a fixed number of columns without considering how the layout behaves on tablets, narrow phones, or large screens. The gallery may look good on your laptop, but on smaller devices the images become too narrow, overflow the container, or create awkward horizontal scrolling.

Problematic approach:

.gallery {
  display: grid;
  grid-template-columns: repeat(4, 1fr);
  gap: 24px;
}

This code always forces four columns, even when the screen is too small. The result is usually tiny thumbnails, broken spacing, or unreadable captions.

Better approach:

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

Pay attention to: Use auto-fit or auto-fill with minmax() when building responsive galleries. This allows the browser to decide how many columns can fit naturally instead of forcing the same layout everywhere.

Real image sets rarely have identical dimensions. Some images are vertical, some are horizontal, and some may be square. If you place them directly into a grid without controlling their size, the gallery can look uneven and unprofessional.

Problematic code:

.gallery img {
  width: 100%;
  height: auto;
}

This preserves the original image proportions, which is useful in some contexts, but for a grid gallery it often creates cards with different heights and irregular rows.

Recommended solution:

.gallery img {
  width: 100%;
  aspect-ratio: 4 / 3;
  object-fit: cover;
  display: block;
}

Pay attention to: Use aspect-ratio and object-fit: cover for thumbnails. This keeps the grid visually consistent while still allowing you to display the full-size image inside the lightbox.

Hover effects should communicate that an image is interactive. Beginners often add aggressive zoom, blur, rotation, or dark overlays that make the gallery feel heavy and distracting. A hover effect should support usability, not become the main feature.

Overdone effect:

.gallery-item:hover img {
  transform: scale(1.4) rotate(8deg);
  filter: blur(2px);
}

This can crop important image details, create motion that feels uncomfortable, and make the gallery harder to scan.

Better effect:

.gallery-item {
  overflow: hidden;
}

.gallery-item img {
  transition: transform 0.25s ease, opacity 0.25s ease;
}

.gallery-item:hover img,
.gallery-item:focus-within img {
  transform: scale(1.05);
  opacity: 0.9;
}

Pay attention to: Keep transitions short and subtle. Also include :focus-within or :focus-visible styles so keyboard users receive the same interaction feedback as mouse users.

A lightbox should focus the user's attention on the selected image. If the background page keeps scrolling while the modal is open, users can lose their position or feel that the interface is unstable. This is especially noticeable on mobile devices.

Incomplete JavaScript:

function openLightbox(imageSrc) {
  lightbox.classList.add('is-open');
  lightboxImage.src = imageSrc;
}

This opens the modal, but the page underneath can still scroll.

Improved version:

function openLightbox(imageSrc) {
  lightbox.classList.add('is-open');
  lightboxImage.src = imageSrc;
  document.body.classList.add('modal-open');
}

function closeLightbox() {
  lightbox.classList.remove('is-open');
  lightboxImage.src = '';
  document.body.classList.remove('modal-open');
}

Supporting CSS:

body.modal-open {
  overflow: hidden;
}

Pay attention to: Always reverse every state change when closing the modal. If you add a class on open, remove it on close. If you set an image source, clear it when the modal closes.

Many beginner lightboxes only work with mouse clicks. This makes the gallery less accessible and less professional. A user should be able to close the preview with Escape, and if your gallery supports multiple images, arrow navigation should be considered as well.

Mouse-only behavior:

closeButton.addEventListener('click', closeLightbox);

Better keyboard-aware behavior:

document.addEventListener('keydown', function (event) {
  if (!lightbox.classList.contains('is-open')) return;

  if (event.key === 'Escape') {
    closeLightbox();
  }

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

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

Pay attention to: Check whether the lightbox is open before reacting to keyboard events. Without this condition, arrow keys may trigger gallery logic even when the user is not viewing the modal.

If your gallery has many images, attaching a separate complex event listener to every item can become harder to maintain. For small galleries this is acceptable, but beginners should understand how event delegation works because it scales better.

Less scalable approach:

const images = document.querySelectorAll('.gallery img');

images.forEach((image) => {
  image.addEventListener('click', () => {
    openLightbox(image.src);
  });
});

More scalable approach:

gallery.addEventListener('click', function (event) {
  const image = event.target.closest('img');

  if (!image) return;

  openLightbox(image.dataset.full || image.src);
});

Pay attention to: Event delegation is especially useful when gallery items are generated dynamically or when you later add filtering, categories, lazy loading, or API-loaded images.