Justified-Gallery

Justified Gallery is a JavaScript library that allows you to create an high quality justified gallery of 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.

The stylesheet keeps entries hidden until they’re positioned, so you don’t see a flash of raw, unpositioned images. This only applies inside a container with the justified-gallery class, since that’s what the CSS targets:

.justified-gallery > a,
.justified-gallery > div,
.justified-gallery > figure {
  opacity: 0;
  /* ... */
}

init() adds that class for you, but not until your script runs. So the hiding won’t actually happen before then unless you also add the class yourself, directly in your markup:

<div id="gallery" class="justified-gallery">...</div>

init() adding the class again is harmless; destroy() still removes it.

This also depends on the CSS itself being loaded before your script runs. The import "justified-gallery/style.css" above takes care of that for bundler setups (bundlers usually put CSS imports into a <link> that loads ahead of your JS). If you’re loading the library from a plain <script> tag or CDN with no build step, link the stylesheet the same way, directly in <head>, before your script tag:

<link
  rel="stylesheet"
  href="https://.../justified-gallery/dist/assets/justified-gallery.css"
/>

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.