@dpouris/gswap v0.5.3

GSwap 🌠

Create a gallery of images with ease.

To get started, in your project folder, run:

npm i @dpouris/gswap

Usage 🔨

First, import the library and create a new gswap instance:

import GSwap from '@dpouris/gswap';

...

const galleryContainer = document.getElementById("gallery")

const gswap = new GSwap({
  containerElem: galleryContainer // or pass the id "gallery",

  images: ["./1.jpg", "./2.jpg", "./3.webp"],

  options : {
    //animation: "fade", -> Todo
    animationDuration: "300",
    navigation: true,
    // repeat: true, -> Todo
    imgDimensions: { height: 300, width: 300 },
  }
});

This will create a new instance of gswap and will place the gallery absolutely inside the container you specified.

• containerElem (required):
  • The container (div) element where the gallery will be placed absolutely or a string value representing the id of an existing div in the document. If none is found the div will be created and be appended at the end of the body.
• images (required):
  • An array of image paths or urls.
• options (optional):
  • An object of options.
  • See the options section for more details.

Options ⚙️

animation (fade | slide | none) -> wip

Takes in an animation eg. fade or slide and applies it to the switching motion of the images.

• fade: Fades the images in and out.
• slide: Slides the images in and out.

• none: Does not apply any animation.

• Default: fade

animationDuration (number)

Takes in the duration of the animation that occurs upon switching the images and the speed at which the images move, in milliseconds. # 1000 = 1 second.

• Default: 300

navigation (boolean | forwardOnly | backOnly)

If true, the navigation arrows will be displayed. # true | false | "forwardOnly" | "backOnly"

• forwardOnly: Only the forward arrow will be displayed.

• backOnly: Only the back arrow will be displayed.

• Default: true

repeat (boolean)

If true, the gallery will loop infinitely. # true || false

• Default: true

direction (top | bottom | left | right)

The direction of the gallery. # top || bottom

styled (boolean)

If true the images will have a nice box shadow and slightly rounded corners. # true || false

imgDimensions (object : {height : number, width: number})

Takes in an object that contains the keys of width and height that will be applied as the dimensions of the images. # { height: 300, width: 300 }

Default: { height: 300, width: 300 }

Methods 🧑‍💻

• gswap.next()
• gswap.prev()
• gswap.goTo(index) -> wip
• gswap.stackImages()

gswap.next()

Displays the next image in the gallery. You can call the next() method by calling it from the gallery instance like so.

const gallery = new GSwap(...);

...

gallery.next();

OR

You can bind the next() method to an onclick event like so.

const gallery = new GSwap(...);
const nextBtn = document.getElementById('nextGalleryBtn')

nextBtn.onclick = gallery.next;

The same concept applies for the .prev() method the only difference being the it moves backwards through the images.

gswap.goTo(index) -> wip

Takes in an index and displays the image at that index.

wip

gswap.stackImages()

Stacks the images in the gallery in case their position was altered.

Can be called from the gallery instance like so.

const gallery = new GSwap(...);

...

gallery.stackImages();

TypeScript 🥰

You can find the types on @dpouris/gswap/dist/types:

import { GallerySwap, Options } from "@dpouris/gswap/dist/types";

GallerySwap

// GSwap
interface GallerySwap {
  containerElem: HTMLDivElement;
  images: string[];
  options: Options;
  stackImages(): void;
  stackImages: () => void;
  next: () => void;
  prev: () => void;
  goTo: (index: number) => void;
}

// Options
type Options = {
  animation?: string,
  animationDuration?: number,
  navigation?: boolean | "forwardOnly" | "backOnly",
  repeat?: boolean,
  direction?: "left" | "right" | "top" | "bottom",
  styled?: boolean,
  imgDimensions?: {
    height: number,
    width: number,
  },
};

React Example 😎

import GSwap from "@dpouris/gswap";
import { GallerySwap } from "@dpouris/gswap/dist/types";
import { useEffect, useRef } from "react";

const Gallery = () => {
  const gallery = useRef<GallerySwap>();

  useEffect(() => {
    if (!document) return;

    const galleryOptions = {
      imgDimensions: { height: 500, width: 600 },
      styled: true,
      repeat: true,
    };

    const imageUrls = [
      "...lqdieniMabM2rLBDJl6XhTwb0=",
      "...softw-office-140335451.jpg",
      "...image-164232735.jpg",
    ];

    gallery.current = new GSwap("gallery", imageUrls, galleryOptions);

  }, [])

  return (
    <div className="flex flex-col items-center justify-center gap-3 my-4">
      <h1 className="text-3xl font-medium text-slate-700 mb-4 border-y-2 border-emerald-400 rounded-lg py-4 px-3 ">
        EVENT GALLERY
      </h1>
      <div id="gallery" className="mx-auto"></div>
      <button
        onClick={() => {
          gallery.current!.goTo(2);
        }}
      >
        GOTO 3RD IMAGE
      </button>
    </div>
  );
};

export default Gallery;

The result is the gif at the start of the README.

• The above example is implemented in Next.js hence the checking for document in the useEffect.

Thank you for trying out my first library and I hope you enjoy it. 🫡