Sweet Sweet Gallery

A zero-dependency tiny utility class to create a gallery of images in a grid of rows taking up the full width of the container while respecting the aspect ratio of the images. See example/index.html for more details.

Why is this different from other gallery libraries? The main goal of this is to provide a way for photos to take entire container width while respecting the aspect ratio of the photos and without clipping the photos themselves. Many other libraries exist but usually provide a cut-off photos (sometimes based on object-fit property) while others fix the height or width of all images and leaving spaces at the end of rows/columns.

Adding to project

pnpm install sweet-sweet-gallery

Importing in a project

import { SweetSweetGallery } from 'sweet-sweet-gallery';

Usage 1: Initializing in an empty container with list of images.

const images: SweetSweetImage[] = [{ src: '' }, { src: '' }, ...moreImages];
const container = document.querySelector('.sweet-sweet-gallery');
const gallery = new SweetSweetGallery({
  images,
  container,
  options: {
    perRowCount: 4,
    gap: 8,
    onClick: (image: SweetSweetImage, imageEl: HTMLImageElement, index: number) {
      console.log("clicked", image, imageEl, index);
    }
  }
});
// To destroy the gallery
gallery.onDestroy();

Usage 2: Initializing in a container with images.

const container = document.querySelector('.sweet-sweet-gallery');
const gallery = SweetSweetGallery.initFromContainer(
  container,
  {
    perRowCount: 4,
    gap: 8,
    onClick: (image: SweetSweetImage, imageEl: HTMLImageElement, index: number) {
      console.log("clicked", image, imageEl, index);
    }
  });
// To destroy the gallery
gallery.onDestroy();

Usage 3: Using in a React component

import { useLayoutEffect, useRef } from 'react';
import { SweetSweetGallery, SweetSweetImage } from 'sweet-sweet-gallery';

export const SweetGallery = ({ photos }: { photos: SweetSweetImage[] }) => {
  const ref = useRef < HTMLDivElement > null;

  useLayoutEffect(() => {
    if (!ref.current) return;

    const gallery = new SweetSweetGallery({
      container: ref.current,
      images: photos,
      options: {
        gap: 8,
        perRowCount: 5,
        onClick: (image, imageEl, index) => {
          console.log('clicked', image, imageEl, index);
        },
      },
    });
    return () => gallery.onDestroy();
  }, [photos]);

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

Contributing

To setup and run the project locally run:

pnpm install
pnpm start

This will kick off the typescript compiler and watch the files to rebuild when changes happen.

To preview the example, run the following command from the root of the project:

npx serve .

Then go to http://localhost:3000/example/

While both of these commands are running you can make changes to the source code and preview the changes in the example.

Credits

Images used in screenshot and examples are from Unsplash.com

LICENSE

MIT