Getting Started

Configuration

Advanced

Help

Version: 1.0.0

Documentation

Complete guide to Vertex Gallery - All parameters, options, and usage examples.

Installation

Install Vertex Gallery via npm to get started with your project.

1. Install via npm

npm install vertex-gallery

Package Installation: After installing, import the package in your project using ES modules, CommonJS, or include it in your HTML. See the Framework Integration section below for specific examples.

Quick Start

Initialize Vertex Gallery with a simple configuration.

const gallery = new VertexGallery(
  document.getElementById('my-gallery'),
  {
    data: [
      {
        thumb: 'thumb.jpg',
        large: 'large.jpg',
        title: 'Image Title',
        desc: 'Image Description',
        category: 'nature'
      }
    ]
  }
);

Framework Integration

Learn how to integrate Vertex Gallery with your favorite framework or use it with vanilla HTML/JavaScript.

React Component

import { useEffect, useRef } from 'react';
import VertexGallery from 'vertex-gallery';
import 'vertex-gallery/dist/vertex-gallery.css';

function GalleryComponent() {
  const galleryRef = useRef<HTMLDivElement>(null);
  const galleryInstanceRef = useRef<any>(null);

  useEffect(() => {
    if (galleryRef.current) {
      // Clean up previous instance if exists
      if (galleryInstanceRef.current) {
        galleryInstanceRef.current.destroy();
      }

      // Initialize gallery
      galleryInstanceRef.current = new VertexGallery(galleryRef.current, {
        data: [
          {
            thumb: 'thumb1.jpg',
            large: 'large1.jpg',
            title: 'Image 1',
            desc: 'Description',
            category: 'nature'
          }
        ]
      });
    }

    // Cleanup on unmount
    return () => {
      if (galleryInstanceRef.current) {
        galleryInstanceRef.current.destroy();
      }
    };
  }, []);

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

export default GalleryComponent;

Tip: Make sure to import both the JavaScript module and CSS stylesheet. Use useEffect to initialize after the component mounts, and always clean up with destroy() in the cleanup function to prevent memory leaks.

Visual Theme

Customize the visual appearance of your gallery with theme options.

cornerStyle

Border radius style for gallery container and cards. 'rounded' applies rounded corners, 'flat' removes all border radius.

Type:

'rounded' | 'flat'

Default:

'rounded'
cornerStyle: 'flat'

showCardShadow

Enable or disable drop shadows on gallery cards for depth effect.

Type:

boolean

Default:

true
showCardShadow: false

galleryMaxWidth

Maximum width of the gallery container. Can be a string with units (e.g., '1200px') or a number (treated as pixels). Set to null for no max-width constraint.

Type:

string | number | null

Default:

null
galleryMaxWidth: '1400px'
galleryMaxWidth: 1200
galleryMaxWidth: null

Grid Layout

Configure the layout and structure of your gallery grid.

layout

Layout type for the gallery. 'grid' creates a uniform grid layout, 'masonry' creates a Pinterest-style masonry layout.

Type:

'grid' | 'masonry'

Default:

'grid'
layout: 'masonry'

columns

Number of columns in the grid. Can be 'auto' for automatic columns, a number for fixed columns, or an object with responsive breakpoints.

Type:

'auto' | number | object

Default:

'auto'
columns: 'auto'
columns: 3
columns: {mobile: 1, tablet: 2, desktop: 3}

gap

Gap between gallery items in pixels.

Type:

number

Default:

16
gap: 24

itemAspectRatio

Aspect ratio for gallery items. Use string format like '16/9' or '4/3'. Set to null for natural aspect ratio. Ignored when layout is 'masonry'.

Type:

string | null

Default:

null
itemAspectRatio: '16/9'
itemAspectRatio: '1/1'
itemAspectRatio: null

Image Filters

Apply CSS filter effects to gallery images for creative styling.

imageFilter

CSS filter effect to apply to gallery images.

Type:

'none' | 'grayscale' | 'sepia' | 'blur' | 'brightness' | 'contrast' | 'saturate'

Default:

'none'
imageFilter: 'grayscale'

imageFilterAmount

Intensity of the filter effect. For grayscale/sepia: 0-100 (0 = no effect, 100 = full effect). For others: 0-200 (100 = normal, 0-99 = reduced, 101-200 = enhanced).

Type:

number

Default:

100
imageFilterAmount: 50  // 50% grayscale
imageFilterAmount: 150 // 150% brightness

imageFilterOnHover

Behavior of filter on hover interaction.

Type:

'color' | 'filter' | 'none'

Default:

'color'

Options: 'color' - Remove filter on hover (show original colors) | 'filter' - Add filter on hover (apply filter effect) | 'none' - No hover effect

Branding

accentColor

Accent color for buttons, active states, and highlights. Accepts any valid CSS color value (hex, rgb, etc.). If null, uses the default CSS variable value.

Type:

string | null

Default:

null
accentColor: '#0005f0'
accentColor: '#10b981'
accentColor: 'rgb(255, 0, 0)'
accentColor: null

Interaction Settings

modalAutoplayInterval

Default autoplay interval in milliseconds. Controls how long each image is displayed before automatically advancing.

Type:

number

Default:

3000
modalAutoplayInterval: 1500  // 1.5 seconds (fast)
modalAutoplayInterval: 3000  // 3 seconds (default)
modalAutoplayInterval: 5000  // 5 seconds (slow)

modalSwipeThreshold

Minimum distance in pixels required to trigger a swipe navigation gesture on touch devices.

Type:

number

Default:

50

Content

data

Array of image objects. Each object represents one image in the gallery.

Type:

Array<ImageObject>

Default:

[]

ImageObject Structure:

{
  thumb: string,      // Thumbnail image URL (required)
  large: string,      // Large/full-size image URL (required)
  title: string,      // Image title (optional)
  desc: string,       // Image description (optional)
  category: string    // Category for filtering (optional)
}
data: [
  {
    thumb: 'thumb1.jpg',
    large: 'large1.jpg',
    title: 'Mountain View',
    desc: 'Beautiful mountain landscape',
    category: 'nature'
  },
  {
    thumb: 'thumb2.jpg',
    large: 'large2.jpg',
    title: 'City Skyline',
    desc: 'Urban architecture',
    category: 'urban'
  }
]

CSS Variables

Vertex Gallery uses CSS custom properties (variables) for complete theming. Override these in your CSS to customize the appearance.

Base Colors

:root {
  --vg-bg-color: #0f172a;
  --vg-card-bg: #1e293b;
  --vg-accent: #0005f0;
  --vg-text-main: #f8fafc;
  --vg-text-muted: #94a3b8;
}

Filter Button Colors

:root {
  --vg-filter-btn-bg: #000000;
  --vg-filter-btn-color: #ffffff;
  --vg-filter-btn-border: #000000;
  --vg-filter-btn-hover-bg: #3333ff;
  --vg-filter-btn-active-color: #ffffff;
}

Customization Example:

/* Override in your CSS */
:root {
  --vg-accent: #10b981;
  --vg-filter-btn-bg: #1f2937;
  --vg-gap: 24px;
}

API Reference

Constructor

new VertexGallery(rootElement, config)

Parameters:

  • rootElement - HTMLElement: The container element for the gallery
  • config - Object: Configuration options (all optional)

Methods

setFilter(category: string)

Set the active filter category. Use 'all' to show all images.

gallery.setFilter('nature');
updateGrid()

Recalculate and update the grid layout (useful after window resize).

openModal(card?: HTMLElement)

Open the modal lightbox. If card is provided, opens that specific image. Otherwise opens the first image.

gallery.openModal(cardElement);
closeModal()

Close the modal lightbox.

nextModalImage()

Navigate to the next image in the modal.

prevModalImage()

Navigate to the previous image in the modal.

toggleModalAutoplay()

Toggle autoplay slideshow. Autoplay automatically pauses when hovering over the modal.

updateModalAutoplaySpeed(interval: number)

Update the autoplay interval in milliseconds.

gallery.updateModalAutoplaySpeed(5000); // 5 seconds
toggleModalTheme()

Toggle between dark and light theme.

toggleThumbnailsVisibility()

Toggle thumbnail strip visibility.

toggleFullscreen()

Toggle fullscreen mode for the modal.

downloadCurrentImage()

Download the currently displayed image in the modal.

shareCurrentImage()

Share the current image via Web Share API or copy link to clipboard.

handleRotate(direction: 'left' | 'right')

Rotate the current image 90 degrees. Also available via the rotate buttons in the transform toolbar.

gallery.handleRotate('left');\ngallery.handleRotate('right');
handleFlip(axis: 'h' | 'v')

Flip the current image horizontally or vertically. Also available via the flip buttons in the transform toolbar.

gallery.handleFlip('h'); // horizontal\ngallery.handleFlip('v'); // vertical
handleZoomIn()

Zoom in on the current image. Also available via the zoom button in the transform toolbar.

handleZoomOut()

Zoom out on the current image. Also available via the zoom button in the transform toolbar.

resetPanZoom()

Reset pan, zoom, rotation, and flip transforms to default. Also available via the reset transform button in the modal toolbar.

gallery.resetPanZoom();
destroy()

Clean up the gallery instance, remove event listeners, and clear intervals. Always call this when removing the gallery from the DOM.

Frequently Asked Questions

Complete Example

React Component Example

// Install first: npm install vertex-gallery

// React Example
import { useEffect, useRef } from 'react';
import VertexGallery from 'vertex-gallery';
import 'vertex-gallery/dist/vertex-gallery.css';

function GalleryComponent() {
  const galleryRef = useRef<HTMLDivElement>(null);
  const galleryInstanceRef = useRef<any>(null);

  useEffect(() => {
    if (galleryRef.current) {
      if (galleryInstanceRef.current) {
        galleryInstanceRef.current.destroy();
      }

      galleryInstanceRef.current = new VertexGallery(galleryRef.current, {
        cornerStyle: 'rounded',
        layout: 'grid',
        columns: 3,
        gap: 20,
        enableModal: true,
        data: [
          {
            thumb: 'thumb1.jpg',
            large: 'large1.jpg',
            title: 'Image 1',
            desc: 'Description',
            category: 'nature'
          }
        ]
      });
    }

    return () => {
      if (galleryInstanceRef.current) {
        galleryInstanceRef.current.destroy();
      }
    };
  }, []);

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