Astro Justified Gallery Layout

My npm package @altner/astro-justified-gallery-layout: a small justified gallery for Astro with EXIF, LQIP previews, a virtual variant and a lightbox.

Article Created Updated Also in German: Astro Justified Gallery Layout

Reviewed by adrian on

For years the photo section of my old site ran on Flickr's justified-layout. It worked, but it no longer matched how I wrote code: a CommonJS module with a UMD browser build and no release since v4.1.0 in January 2021. For the next version of the photo section and a few other Astro projects I wanted something that felt like an Astro component from the start, so I wrote one. In April 2026 the first public version came out: @altner/astro-justified-gallery-layout.

It is a fresh take in the tradition of Flickr's original. Much smaller, ESM only, TypeScript types bundled, zero runtime dependencies in the core, plus the building blocks I needed for a real photo site.

What the package contains

  • <JustifiedGallery />: the default component. It reflows when the container changes size (ResizeObserver), uses Astro's <Image /> for optimisation and can render long lists in chunks via IntersectionObserver.
  • <JustifiedGalleryVirtual />: DOM windowing for very large collections. The server renders an empty container; the client fetches metadata in chunks from a JSON endpoint and keeps only the visible rows in the DOM.
  • <Lightbox />: a native <dialog> modal with arrow keys, swipe, ESC and backdrop close. You place it once on the page and switch it on per gallery with the lightbox prop.
  • galleryLoader(): an Astro content loader that scans a directory. Optionally it reads EXIF, IPTC, XMP and GPS via exifr and generates LQIP previews via sharp, base64 placeholders of about 1 KB for an instant first paint.
  • computeLayout(): the pure function behind it all. About 120 lines, independent of any framework, usable outside Astro.
  • readPhotoMeta() / formatCameraLine(): helpers that turn EXIF into a readable line such as Sony ILCE-7M3 · 35mm · f/2.8 · 1/250s · ISO 400.

Minimal example

---
import JustifiedGallery from '@altner/astro-justified-gallery-layout/JustifiedGallery.astro';
import Lightbox from '@altner/astro-justified-gallery-layout/Lightbox.astro';
import type { ImageMetadata } from 'astro';

const modules = import.meta.glob<{ default: ImageMetadata }>(
    '../assets/photos/*.{jpg,jpeg,png,webp,avif}',
    { eager: true },
);
const images = Object.values(modules).map((m) => ({ src: m.default }));
---

<JustifiedGallery
    images={images}
    targetRowHeight={240}
    gap={6}
    chunkSize={30}
    lightbox
/>
<Lightbox />

That is the whole setup. Put photos into the directory, run astro dev, and you get lazy loading, LQIP placeholders and the lightbox.

How a row is closed

The interesting part is in computeLayout(). As images are added to a row, the function calculates the height the row would need to fill the container width exactly. Once that height drops to or below the target, it compares two options:

  1. Close the row with the current image.
  2. Close the row without it, so the image moves to the next row.

Whichever is closer to the target height wins. That avoids both huge single-image rows and squashed thin rows. The last, incomplete row stays left-aligned at target height, because three landscape photos stretched across 1500 px look silly.

computeLayout() is deterministic, with no DOM access and no side effects. It is easy to memoise and runs in a Web Worker.

Compared with Flickr's package

this package (core) flickr/justified-layout
Size ~120 LOC, ~1 kB min+gz ~10 kB minified, ~2.5 kB gz
Module format ESM only UMD (Node style)
Dependencies 0 0
TypeScript types bundled DefinitelyTyped, often stale
Astro component bundled none
Last release v0.6.0 (Apr 2026) v4.1.0 (Jan 2021)

The figures for Flickr's package come from version 4.1.0 as published on npm.1

exifr and sharp are optional peer dependencies. If you need no metadata or LQIPs, leave them out. A missing peer degrades quietly: no crash, just no feature.

Why my own site did not use it yet

At the time the honest answer was: eventually, but not yet. The photo section had grown its own logic. It had a hierarchical photo tree with an index.md per set and pre-generated JSON sidecars with EXIF, IPTC and GPS. Each photo had titles in several languages, and URL segments differed per locale. Statistics and world map views sat on top of that data shape. galleryLoader() expects a flat collection with a different EXIF schema and knows nothing about i18n. Dropping it in would have broken half the site.

The bigger break was the workflow. The package reads tags, title, description and GPS straight from the image file, not from separate JSON sidecars. So photos need preparation in Lightroom or another DAM before export: the IPTC fields Title, Description and Keywords filled in, and an export preset that keeps IPTC and GPS in the JPG. Otherwise the fields read back empty.

The upside is a single source of data: every photo carries its own metadata. The downside is that the existing JSON files would have to be written back into the images, or the loader would need a hybrid mode that reads both. I planned to switch only during the next larger rework of the photo stack. That rework would bring clean IPTC fields from Lightroom, mapped data structures, a layer for the set hierarchy and a translation step for GPS and camera data. Later I did move the layout function on its own: Replacing justified-layout with my own package.

Install

Version 0.6.0, MIT licence, on npm:

npm install @altner/astro-justified-gallery-layout

The source is in the monorepo on GitHub, issues go to the tracker.

Based on

  • Astro Justified Gallery Layout: a modern replacement for the Flickr classic (raw/2026/2026-04-29/astro-justified-gallery-layout-a-modern-replacement-for-the-flickr-classic.md) [post]
  • justified-layout 4.1.0 on npm [npm]

More on this

Topic

  • Static Website A website made of finished HTML files that are built once and then served unchanged. No server code, no database.

Basis for

Uses

  • Astro Tool for building websites from content such as Markdown. Ships plain HTML by default and only loads JavaScript where it is needed.

Mentioned

  • Photo Sidecars with a Vision Model The script vision.ts of my old site: EXIF data and a vision model's alt text, titles and tags in a JSON file next to each photo, generated locally before the deploy.

Show in the graph view