Mosaic Gallery

To try out the different features and configuration options of this gallery, head over to the Playground.

Installation

Install the latest version from npmjs.

npm i mosaicgallery

Otherwise, the package can be downloaded from the latest Gitlab release.

Usage

MosaicGallery accepts a standard gallery layout, where the container (must be a div) contains a number of children elements. Each child will represent one image of the gallery. The child can contain different elements, e.g. a link that points to the image which contains the img element. However, each child must contain exactly one img element which contains the desired image.

<a class="mosaic-gallery-element" href="/img1.jpg">
    ><img src="/img1.jpg" />
</a>
<a class="mosaic-gallery-element" href="/img2.jpg">
    ><img src="/img2.jpg" />
</a>
<a class="mosaic-gallery-element" href="/img3.jpg">
    ><img src="/img3.jpg" />
</a>

To construct the gallery, simply create the MosaicGallery class with the appropriate HTMLDivElement and your desired configuration from your typescript code. Afterwards, the gallery will automatically react to updates to its size. However, new elements won't be recognized automatically. To update the elements of the gallery call updateElements() on it.

import { MosaicGallery, HoverEffect } from "mosaicgallery";
import "mosaicgallery/style.css";

const galleryElement = document.querySelector<HTMLDivElement>("#my-gallery");
if (galleryElement) {
  const gallery = new MosaicGallery(galleryElement, {
    hoverEffect: HoverEffect.Scale,
    layout: {
      type: "justified",
      targetRowHeight: 150,
      margin: [5, 5],
    },
  });
}

Don't forget to include the style.css file to get the required stylesheet. For further details and configuration options, refer to the API Reference.

Plain Javascript

You can also use this library without a dedicated bundler. The library is built both as a UMD file and a modern ES module. Download the latest release from Gitlab to obtain the library files from the dist/ folder of the package.

For brevity, we will only show the modern method using the ES module in this guide. First, simply include the the mosaic-gallery.css file as a stylesheet. Then, in your script tag use the import syntax with the mosaic-gallery.js file. Do note that most browsers will block this when serving a straight html file (file://), so the files have to be served by a local server (e.g. npx serve .).

<link rel="stylesheet" href="./mosaic-gallery.css" />
<script type="module">
  import { MosaicGallery, HoverEffect } from "./mosaic-gallery.js";
  
  const galleryElement = document.querySelector("#my-gallery");
  if (galleryElement) {
      const gallery = new MosaicGallery(galleryElement, {
          hoverEffect: HoverEffect.Scale,
          layout: {
              type: "justified",
              targetRowHeight: 150,
              margin: [5, 5],
          },
      });
  }
</script>

Performance Optimizations

To already start with the layout calculations, even when the images haven't been loaded yet, an explicit size can be specified for the images.

<a class="mosaic-gallery-element" href="/img3.jpg">
    ><img src="/img3.jpg" width="5000" height="3000" />
</a>

Lazy Loading

This library also supports lazy loading. I.e. the image displayed initially is a low resolution image that is quick to load and the full resolution image will only be displayed once the image is visible on the screen. Especially for very large galleries this can speed up page load times immensely. As an additional optimization, the initial low resolution image can be embedded into the html to save an additional network request.

Do make sure that the aspect ratio of the initial image matches that of your lazily loaded full resolution image. Otherwise the gallery will use the wrong aspect ratio for layout calculations. The onImageReady callback will be called twice for any image using lazy loading. First, with the dimensions of the initial low resolution image and then again, when the full resolution image was loaded.

<a class="mosaic-gallery-element" href="/high-resolution-image.jpg"
    ><img src="data:image/png;base64,..." mscglry-data-src="/high-resolution-image.jpg"
/></a>