Justified Gallery

Elegant, Professional, Endless.Crafted by Miro Mannino

Read the docs GitHub Repo

Justified Gallery is a JavaScript library that allows you to create a high quality justified gallery of images.

This is a common problem for people who create websites: you have a series of images to display, but you are not sure how to arrange them in an elegant way. Important websites such as 500px, Flickr, or Google display images in an excellent way, justifying them similarly to a brick wall. Justified Gallery will give you the power to do that too.

Justified Gallery is a professional and open source library that even 500px, one of the best photography social networks, chose for displaying their images!

Install

npm install justified-gallery

How to use it

Justified Gallery accepts a standard format for a gallery: a series of links with a thumbnail inside, where each link leads to the original image.

<div id="mygallery" class="justified-gallery">
  <a href="path/to/myimage1_original.jpg">
    <img alt="Title 1" src="path/to/myimage1_thumbnail.jpg" />
  </a>
  <a href="path/to/myimage2_original.jpg">
    <img alt="Title 2" src="path/to/myimage2_thumbnail.jpg" />
  </a>
  <!-- other images... -->
</div>

Justified Gallery also accepts other input formats, to better fit your needs.

Import the library and its stylesheet, then create a gallery instance and initialize it — no jQuery or other dependencies needed:

import { JustifiedGallery } from "justified-gallery";
import "justified-gallery/style.css";

new JustifiedGallery(document.querySelector("#mygallery")).init();

Note the justified-gallery class already on the container above — the stylesheet uses it to hide the gallery until it’s properly laid out, avoiding a flash of unstyled images.

Start learning how to use Justified Gallery from the getting started tutorial.

Features

TypeScript types included

Works everywhere

Zero dependencies, no jQuery. A plain class working on a real DOM element, so it drops into any stack with no wrapper needed.

import { JustifiedGallery } from 'justified-gallery';
import 'justified-gallery/style.css';

new JustifiedGallery(
  document.querySelector('#gallery')
).init();

const ref = useRef(null);

useEffect(() => {
  const jg = new JustifiedGallery(ref.current);
  jg.init();
  return () => jg.destroy();
}, []);

return <div ref={ref}>{images}</div>;

const el = ref(null);
let jg;

onMounted(() => {
  jg = new JustifiedGallery(el.value);
  jg.init();
});

onBeforeUnmount(() => jg.destroy());

Lightbox friendly

Plays nicely with GLightbox, PhotoSwipe and friends, with link attributes and lazy-loading-safe sources handled for you.

Automatic captions

Elegant captions generated from your images’ alt or title attributes, fully styleable and on by default.

Don't miss a pixel

An advanced justification algorithm sizes every row to fill the available width without ever cropping or distorting your images.

The right thumbnail, automatically

Loads (and hot-swaps) the best thumbnail size for each image, so you never download more pixels than needed and never see a blurry upscale.

Fast, progressive rendering

Non-blocking, row-by-row fade-in as thumbnails load, with a built-in spinner while the gallery grows.

Truly responsive

Watches the gallery’s own container width — not just the window — so it adapts to sidebars, flex layouts and anything else that resizes it.

Your rows, your rules

Six last-row behaviors, row height and margin controls, RTL support and many more options to build exactly the gallery you want.

Endless scroll ready

Build an infinite wall of images: append new entries and notify the gallery — new rows justify without rebuilding what’s already placed.

Events & clean teardown

Lifecycle events for every row and layout pass, plus a destroy method that restores your markup — ideal for single-page apps.

Dynamic galleries

Sort, randomize, filter, add or remove images. Do what you want with the gallery, even after it has been created.

Flexible input, silent errors

Links, divs or figures, images or inline SVG — and broken images are skipped gracefully, reported only in the console.

Project stats

Monthly npm downloads (last 24 months), combined across justified-gallery and legacy justifiedGallery

Contributors

Justified Gallery is built with help from these contributors:

semantic-release-bot · 3

Who uses it?

Some examples of uses of this library:

500px

One of the biggest photography social networks chose Justified Gallery to display millions of photos.

Flickr Justified Gallery for WordPress

Plugin that shows your Flickr photostream, photosets, galleries, group pools, or tags in your blog with an elegant layout.

FooGallery Plugin for WordPress

An intuitive and extensible gallery creation and management tool for WordPress.

ACF Justified Image Grid Addon

WordPress plugin to create justified galleries.

Help the project!

This is an open source project, released under the MIT license. You can help it grow in various ways: talking about it in blogs and social networks, starring the repository, or contributing your own features with a pull request.

Any issue?

If you have any issue, please post your question on the GitHub issues page, where you may also find existing answers.