@eztrak/gallery

Reusable image gallery, carousel, and preview components for EzTrak applications.

Installation

npm install @eztrak/gallery

Peer Dependencies

npm install react react-dom react-icons framer-motion

Quick Start

import { GalleryCarousel } from "@eztrak/gallery";

const images = [
  { id: "1", url: "/uploads/photo1.jpg", name: "Site photo" },
  { id: "2", url: "/uploads/photo2.jpg", name: "Progress shot" },
  { id: "3", url: "/uploads/photo3.png", name: "Blueprint" },
];

function MyComponent() {
  return (
    <GalleryCarousel
      images={images}
      baseUrl="https://api.example.com"
      viewMode="grid"
      enableDownload
      enableRotate
      enableDelete
      enableZoom
      onDelete={(image, index) => {
        // call your API to delete
      }}
      onRotate={(image, index) => {
        // call your API to rotate
      }}
    />
  );
}

Components

GalleryCarousel

The all-in-one gallery component with view mode switching and built-in fullscreen preview.

| Prop | Type | Default | Description | |------|------|---------|-------------| | images | GalleryImage[] | required | Array of image objects | | baseUrl | string | "" | Base URL to prefix relative paths | | viewMode | "grid" \| "carousel" \| "list" | "grid" | Active view mode | | enableViewModeSwitch | boolean | true | Show view mode switcher | | enableDownload | boolean | true | Enable download action | | enableRotate | boolean | false | Enable rotation action | | enableDelete | boolean | false | Enable delete action | | enableZoom | boolean | true | Enable zoom in preview | | enableFullscreen | boolean | true | Enable fullscreen mode | | enableMultiSelect | boolean | false | Enable multi-selection | | onDownload | (image, index) => void | - | Custom download handler | | onDownloadMultiple | (images) => void | - | Bulk download handler | | onRotate | (image, index) => void | - | Rotation callback | | onDelete | (image, index) => void | - | Delete callback | | onImageClick | (image, index) => void | - | Override click behavior | | onViewModeChange | (mode) => void | - | View mode change callback | | thumbnailSize | string | "w-28 h-28" | Tailwind classes for thumbnail size | | maxVisibleItems | number | - | Max items in grid (shows "+N more") | | columns | number | - | Grid columns count | | zIndex | number | 1250 | z-index for overlay | | isLoading | boolean | false | Show loading spinner | | emptyMessage | string | "No images found" | Empty state text | | renderEmpty | () => ReactNode | - | Custom empty state |

ImagePreview

Standalone fullscreen image preview with toolbar (zoom, rotate, download, delete, navigate).

import { ImagePreview } from "@eztrak/gallery";

<ImagePreview
  images={images}
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  initialIndex={0}
  baseUrl="https://api.example.com"
  enableDownload
  enableRotate
  enableDelete
  enableZoom
  onDelete={handleDelete}
  onRotate={handleRotate}
/>

Keyboard shortcuts: Esc close, Left/Right navigate, +/- zoom, R rotate, 0 reset zoom.

GridView

Thumbnail grid layout with hover overlays for zoom/delete.

import { GridView } from "@eztrak/gallery";

<GridView
  images={images}
  baseUrl="https://api.example.com"
  onImageClick={(image, index) => openPreview(index)}
  enableDelete
  onDelete={handleDelete}
  columns={4}
  maxVisibleItems={8}
/>

CarouselView

Inline carousel with prev/next navigation and thumbnail strip.

import { CarouselView } from "@eztrak/gallery";

<CarouselView
  images={images}
  baseUrl="https://api.example.com"
  selectedIndex={selectedIndex}
  onIndexChange={setSelectedIndex}
  onImageClick={handleClick}
/>

ListView

Compact file list with thumbnails and action buttons.

import { ListView } from "@eztrak/gallery";

<ListView
  images={images}
  baseUrl="https://api.example.com"
  onImageClick={handleClick}
  enableDownload
  enableDelete
  onDownload={handleDownload}
  onDelete={handleDelete}
/>

ViewModeSwitcher

Standalone toggle buttons for switching view modes.

import { ViewModeSwitcher } from "@eztrak/gallery";

<ViewModeSwitcher
  viewMode={viewMode}
  onChange={setViewMode}
/>

ConfirmDialog

Built-in animated confirmation dialog (used internally for delete, also exported).

import { ConfirmDialog } from "@eztrak/gallery";

<ConfirmDialog
  isOpen={showConfirm}
  onConfirm={() => performDelete()}
  onCancel={() => setShowConfirm(false)}
  title="Delete Image"
  message="This action cannot be undone."
/>

Hooks

useGalleryState

Manages gallery state: selected index, view mode, preview open/close, multi-selection.

import { useGalleryState } from "@eztrak/gallery";

const {
  normalizedImages,
  imageOnlyFiles,
  selectedIndex,
  setSelectedIndex,
  viewMode,
  setViewMode,
  isPreviewOpen,
  openPreview,
  closePreview,
  selectedImages,
  toggleSelect,
  selectAll,
  clearSelection,
  getSelectedImages,
} = useGalleryState({ images, initialIndex: 0, initialViewMode: "grid" });

useImageTransform

Manages zoom, rotation, and pan state for an image preview.

import { useImageTransform } from "@eztrak/gallery";

const { transform, transformStyle, rotate, zoomIn, zoomOut, reset } =
  useImageTransform();

Utilities

import {
  downloadImage,
  downloadMultipleImages,
  buildFullUrl,
  getFileName,
  isImageFile,
  getFileExtension,
  getVersionedUrl,
} from "@eztrak/gallery";

GalleryImage Type

interface GalleryImage {
  id?: string | number;
  url: string;
  name?: string;
  serverUrl?: string;
  [key: string]: unknown;
}

Migrating from app-level components

This package replaces duplicated components across EzTrak apps:

| Old component | New equivalent | |---|---| | FileGallery (elite-pilot, vault) | <GalleryCarousel viewMode="grid" /> | | GenericImageCarousel (elite-pilot) | <ImagePreview /> | | ImageViewerModal (elite-pilot, vault) | <ImagePreview /> (single image) |

Key differences:

• No API coupling - delete/rotate/download are callback-based, not tied to Redux RTK Query mutations.
• baseUrl prop replaces hardcoded BASE_GATEWAY_URL.
• Built-in zoom, fullscreen, keyboard shortcuts that the old components lacked.
• View mode switching between grid/carousel/list in a single component.