usecueweb development

Tiled Mosaic Gallery by Usecue

Close
  • readme.txt
  • index.html
  • mosaic.js

What is it?

While converting a website from WordPress to Hugo and needed an equivalent to the Tiled Image Gallery from Wordpress. I wanted the Tiled Mosaic style, but that was a little too complex, as it also contains colspans. I came up with this as an alternative.

How to use it?

It requires only Javascript and a simple HTML structure, as illustrated below:

<div class="mosaic-gallery">
   <a href="full_img.jpg">
      <img ratio="0.666" src="thumb_img.jpg" />
   </a>
   ...
</div>
<script src="mosaic.js"></script>

Caveats

The hardest part of using this code is determining the image ratio of every image before rendering. Any server side language (like PHP) can generate these image ratios though, as can Hugo. Knowing the image ratio before loading the images prevents layout shifts and ensures a smooth loading experience.

Features

This whole javascript is only a few kilobytes large, so it loads relatively quickly. It is fully responsive and has a debounce function that limits the redraws to 50ms, preventing it from being CPU-heavy. Aestheticly, it aims for about 1 image every 700px of width. The images always fill out nicely and the code prevents subpixel issues. Images have a minimum size, which turns the gallery into a list of images on mobile.

License

This code is licensed WTFPL.

<div class="mosaic-gallery">
    <a href="large01.jpg">
        <img data-ratio="0.666" src="01.jpg" alt="01" loading="lazy" />
    </a><a href="large02.jpg">
        <img data-ratio="1.43" src="02.jpg" alt="02" loading="lazy" />
    </a><a href="large03.jpg">
        <img data-ratio="1.5" src="03.jpg" alt="03" loading="lazy" />
    </a><a href="large04.jpg">
        <img data-ratio="1.5" src="04.jpg" alt="04" loading="lazy" />
    </a><a href="large05.jpg">
        <img data-ratio="1.5" src="05.jpg" alt="05" loading="lazy" />
    </a><a href="large06.jpg">
        <img data-ratio="1.5" src="06.jpg" alt="06" loading="lazy" />
    </a><a href="large07.jpg">
        <img data-ratio="1.5" src="07.jpg" alt="07" loading="lazy" />
    </a><a href="large08.jpg">
        <img data-ratio="1.43" src="08.jpg" alt="08" loading="lazy" />
    </a><a href="large09.jpg">
        <img data-ratio="1.5" src="09.jpg" alt="09" loading="lazy" />
    </a><a href="large10.jpg">
        <img data-ratio="1.38" src="10.jpg" alt="10" loading="lazy" />
    </a><a href="large11.jpg">
        <img data-ratio="1.41" src="11.jpg" alt="11" loading="lazy" />
    </a><a href="large12.jpg">
        <img data-ratio="1.5" src="12.jpg" alt="12" loading="lazy" />
    </a><a href="large13.jpg">
        <img data-ratio="0.666" src="13.jpg" alt="13" loading="lazy" />
    </a><a href="large14.jpg">
        <img data-ratio="1.40" src="14.jpg" alt="14" loading="lazy" />
    </a><a href="large15.jpg">
        <img data-ratio="1.64" src="15.jpg" alt="15" loading="lazy" />
    </a><a href="large16.jpg">
        <img data-ratio="1.39" src="16.jpg" alt="16" loading="lazy" />
    </a><a href="large17.jpg">
        <img data-ratio="0.61" src="17.jpg" alt="17" loading="lazy" />
    </a>
</div>

<script src="/demos/mosaic/mosaic.js"></script>

<link rel="stylesheet" href="/demos/lightbox/lightbox.css" />
<script src="/demos/lightbox/lightbox.js"></script>
const gallery = document.querySelector('div.mosaic-gallery');
gallery.style.width = '100%';
gallery.style.display = 'flex';
gallery.style.flexWrap = 'wrap';
gallery.style.overflow = 'hidden';
gallery.style.padding = 0;
gallery.style.margin = 0;
const links = Array.from(gallery.querySelectorAll('a'));
links.forEach(function(image) {
  image.style.display = 'inline-block';
  image.style.verticalAlign = 'bottom';
  image.style.padding = 0;
  image.style.margin = 0;
  image.style.border = 'none';
  image.style.textDecoration = 'none';
  image.querySelector('img').style.display = 'inline-block';
  image.querySelector('img').style.margin = 0;
  image.querySelector('img').style.border = 0;
  image.querySelector('img').style.verticalAlign = 'bottom';
  image.querySelector('img').style.lineHeight = 0;
  image.querySelector('img').style.marginBottom = '4px';
});

function justifyGallery() {
    const containerWidth = Math.floor(gallery.getBoundingClientRect().width);
    const images = Array.from(gallery.querySelectorAll('img'));
    const margin = 4; // px, space between images
    const maxImageWidth = 700; // px
    const minImagesPerRow = Math.ceil(containerWidth/maxImageWidth);
    const maxImagesLastRow = Math.ceil(containerWidth/maxImageWidth)+1;

    let rows = [];
    let idx = 0;

    // Build rows aiming for minImagesPerRow images per row, but allow more if needed
    while (idx < images.length) {
        let row = [];
        let rowRatios = 0;
        let rowEnd = false;

        while (!rowEnd && idx < images.length) {
            const img = images[idx];
            const ratio = parseFloat(img.dataset.ratio) || 1;
            row.push({ img, ratio });
            rowRatios += ratio;

            const gutters = (row.length - 1) * margin;
            let rowHeight = (containerWidth - gutters) / rowRatios;
            let widths = row.map(({ ratio }) => Math.round(rowHeight * ratio));
            let tooWide = widths.some(w => w > maxImageWidth);

            // If we have at least minImagesPerRow and no image is too wide, break
            if ((row.length >= minImagesPerRow && !tooWide) || idx === images.length - 1) {
                rowEnd = true;
            } else if (tooWide && idx < images.length - 1) {
                idx++;
            } else {
                rowEnd = true;
            }
        }

        rows.push({ row, rowRatios });
        idx++;
    }

    // Ensure last row has at least minImagesPerRow images (unless total images < 3 or gallery is narrow)
    while (
        rows.length > 1 &&
        rows[rows.length - 1].row.length < minImagesPerRow &&
        containerWidth >= 600
    ) {
        const lastRow = rows.pop();
        rows[rows.length - 1].row = rows[rows.length - 1].row.concat(lastRow.row);
        rows[rows.length - 1].rowRatios += lastRow.rowRatios;
    }

    // If last row has more than maxImagesLastRow images, move extras to previous rows
    while (
        rows.length > 1 &&
        rows[rows.length - 1].row.length > maxImagesLastRow
    ) {
        const lastRow = rows[rows.length - 1];
        const prevRow = rows[rows.length - 2];

        if (lastRow.row.length > maxImagesLastRow) {
            const moved = lastRow.row.shift();
            lastRow.rowRatios -= moved.ratio;
            prevRow.row.push(moved);
            prevRow.rowRatios += moved.ratio;
        } else {
            break;
        }
    }

    rows.forEach(({ row, rowRatios }) => {
        const gutters = (row.length - 1) * margin;
        let rowHeight = (containerWidth - gutters) / rowRatios;

        let widths = row.map(({ ratio }) => Math.round(rowHeight * ratio));
        let roundedHeight = Math.round(rowHeight);

        let totalWidth = widths.reduce((a, b) => a + b, 0) + gutters;
        let diff = containerWidth - totalWidth;

        widths[widths.length - 1] += diff;

        row.forEach(({ img }, i) => {
            img.style.height = `${roundedHeight}px`;
            img.style.width = `${widths[i]}px`;
            img.style.marginRight = (i < row.length - 1) ? `${margin}px` : '0';
        });
    });
}

function debounce(fn, delay) {
    let timeoutId;
    return function (...args) {
        clearTimeout(timeoutId);
        timeoutId = setTimeout(() => {
            fn.apply(this, args);
        }, delay);
    };
}

// Debounce it with 50ms delay
const debouncedResize = debounce(justifyGallery, 50);

// Attach to event
window.addEventListener("resize", debouncedResize);

justifyGallery();