Justified Gallery is a JavaScript library that allows you to create an 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 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 chose for displaying their images!

(combined across justified-gallery and legacy justifiedGallery npm packages)

Usage

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

const gallery = document.getElementById("gallery");
const jg = new JustifiedGallery(gallery);
jg.init();

// later, on unmount:
jg.destroy();

JustifiedGallery is a plain class working against a real HTMLElement, so it integrates the same way in any framework: get a ref to the container, call init() once it's mounted, and call destroy() on cleanup. See test/browser/html/react_gallery.tsx and test/browser/html/vue_gallery.vue for working React and Vue examples.

Contributing

• Prerequisites:

  • Node.js
  • npm install to install all dependencies.

• Develop:

  • npm run dev starts a Vite dev server against test/browser, serving the source directly (no build step needed while iterating). In this mode /text/browser/html pages can be explored. These are the same pages used by the e2e tests.

• Build:

  • npm run build compiles the library for distribution: bundles src/justified-gallery.ts with Vite into dist/justified-gallery.js and dist/assets/justified-gallery.css, and emits type declarations (dist/*.d.ts) with tsc.
  • npm run preview serves the built dist output locally.

• Test:

  • npm test runs the full suite (unit tests, then browser/e2e tests).
  • npm run test:unit runs the Vitest unit tests in test/unit.
  • npm run test:e2e runs the Playwright browser tests in test/browser.

• Try the built package as a real npm dependency:

  • scripts/test-local-package.sh builds the library, npm links it, and links/serves it from sandbox-consumer/ (a throwaway, gitignored Vite project) — useful to confirm the published package resolves and works the way a downstream consumer would experience it.