Types

Complete TypeScript type definitions for VistaView.

Core Types

VistaParams

Main configuration interface including the elements property.

interface VistaParams extends VistaOpt {
  elements: string | VistaImgConfig[];
}

Properties:

elements (required): CSS selector string or array of VistaImgConfig configurations
Extends VistaOpt with all configuration options

VistaOpt

Base configuration options interface.

interface VistaOpt {
  // Animation
  animationDurationBase?: number;

  // Zoom
  maxZoomLevel?: number;

  // Preloading
  preloads?: number;

  // Interaction
  keyboardListeners?: boolean;
  arrowOnSmallScreens?: boolean;
  rapidLimit?: number;

  // Styling
  initialZIndex?: number;

  // Controls
  controls?: {
    topLeft?: (VistaDefaultCtrl | string)[];
    topRight?: (VistaDefaultCtrl | string)[];
    topCenter?: (VistaDefaultCtrl | string)[];
    bottomCenter?: (VistaDefaultCtrl | string)[];
    bottomLeft?: (VistaDefaultCtrl | string)[];
    bottomRight?: (VistaDefaultCtrl | string)[];
  };

  // Extensions
  extensions?: VistaExtension[];

  // Event Callbacks
  onOpen?: (vistaView: VistaView) => void;
  onClose?: (vistaView: VistaView) => void;
  onImageView?: (data: VistaData, vistaView: VistaView) => void;
  onContentChange?: (content: VistaImageClone, vistaView: VistaView) => void;

  // Lifecycle Functions
  initFunction?: VistaInitFn;
  imageSetupFunction?: VistaImageSetupFn;
  transitionFunction?: VistaTransitionFn;
  openFunction?: VistaOpenFn;
  closeFunction?: VistaCloseFn;
}

Related Types:

VistaDefaultCtrl - Control names
VistaExtension - Extension system
VistaData, VistaImageClone - Event data
VistaInitFn, VistaImageSetupFn, VistaTransitionFn, VistaOpenFn, VistaCloseFn - Lifecycle functions

VistaInterface

Instance interface with control methods returned by vistaView().

interface VistaInterface {
  open(index?: number): void;
  close(): Promise<void>;
  view(index: number): void;
  next(): void;
  prev(): void;
  reset(): void;
  zoomIn(): void;
  zoomOut(): void;
  getCurrentIndex(): number;
  destroy(): void;
}

Methods:

open(index?) - Opens lightbox at specified index
close() - Closes lightbox (returns Promise)
view(index) - Navigate to specific image
next() - Navigate to next image
prev() - Navigate to previous image
reset() - Recalculate elements and re-attach event listeners (useful after DOM changes)
zoomIn() - Zoom in
zoomOut() - Zoom out
getCurrentIndex() - Get current image index
destroy() - Destroy instance and cleanup

VistaImgConfig

Image configuration object.

interface VistaImgConfig {
  src: string;
  alt?: string;
  srcSet?: string;
}

Properties:

src (required): Image URL
alt (optional): Alt text for accessibility
srcSet (optional): Responsive image sources

Event Data Types

VistaData

Data passed to event callbacks and transition functions.

interface VistaData {
  htmlElements: {
    from: HTMLElement[] | null;
    to: HTMLElement[] | null;
  };
  images: {
    from: VistaBox[] | null;
    to: VistaBox[] | null;
  };
  index: {
    from: number | null;
    to: number | null;
  };
  via: {
    next: boolean;
    prev: boolean;
  };
}

Properties:

htmlElements.from - Previous HTML elements
htmlElements.to - New HTML elements
images.from - Previous image objects
images.to - New image objects
index.from - Previous image index (null on initial open)
index.to - New image index
via.next - True if navigated via next
via.prev - True if navigated via previous

VistaImageClone

Current image state passed to onContentChange callback.

interface VistaImageClone {
  config: {
    src: string;
    alt?: string;
    srcSet?: string;
  };
  origin: {
    src: string;
    srcSet: string;
    borderRadius: string;
    objectFit: string;
  } | null;
  parsedSrcSet?: { src: string; width: number }[];
  element: string;
  thumb?: string;
  index: number;
  pos: number;
  state: {
    width: number;
    height: number;
    transform: {
      x: number;
      y: number;
      scale: number;
    };
    translate: {
      x: number;
      y: number;
    };
  };
}

Properties:

config - Image configuration (src, alt, srcSet)
origin - Original element properties (null for non-image content)
parsedSrcSet - Parsed srcSet attribute
element - HTML string of the content
thumb - Thumbnail URL (if applicable)
index - Current image index
pos - Position in the view
state.width - Current width
state.height - Current height
state.transform - Transform state (x, y, scale)
state.translate - Translation offsets (x, y)

VistaParsedElm

Parsed element information passed to extensions.

interface VistaParsedElm {
  config: VistaImgConfig;
  parsedSrcSet?: { src: string; width: number }[];
  origin?: VistaImgOrigin;
}

Properties:

config - Image configuration (VistaImgConfig)
parsedSrcSet - Parsed srcSet attribute with sources and widths
origin - Origin element properties (VistaImgOrigin)

VistaImgOrigin

Origin element properties for animations.

interface VistaImgOrigin {
  anchor?: HTMLAnchorElement;
  image: HTMLImageElement;
  src: string;
  srcSet: string;
  borderRadius: string;
  objectFit: string;
}

Properties:

anchor - The original anchor element (if exists)
image - The original image element
src - Original image source
srcSet - Original srcSet attribute
borderRadius - Original border radius style
objectFit - Original object-fit style

Lifecycle Function Types

VistaInitFn

Type for custom initialization function.

type VistaInitFn = (vistaView: VistaView) => void;

Parameters:

vistaView: VistaView - The VistaView instance

VistaImageSetupFn

Type for custom setup function when navigating between images.

type VistaImageSetupFn = (data: VistaData, vistaView: VistaView) => void;

Parameters:

data: VistaData - Navigation data
vistaView: VistaView - The VistaView instance

VistaTransitionFn

Type for custom transition animation function.

type VistaTransitionFn = (
  data: VistaData,
  abortSignal: AbortSignal,
  vistaView: VistaView
) => { cleanup: () => void; transitionEnded: Promise<void> } | void;

Parameters:

data: VistaData - Navigation data
abortSignal: AbortSignal - Signal to abort the transition
vistaView: VistaView - The VistaView instance

Returns: Object with cleanup function and promise, or void

VistaOpenFn

Type for custom open function.

type VistaOpenFn = (vistaView: VistaView) => void;

Parameters:

vistaView: VistaView - The VistaView instance

VistaCloseFn

Type for custom close function.

type VistaCloseFn = (vistaView: VistaView) => void;

Parameters:

vistaView: VistaView - The VistaView instance

Extension Types

VistaExtension

Interface for creating extensions.

interface VistaExtension {
  name: string;
  description?: string;
  control?: () => HTMLElement | null;
  onInitializeImage?: (parsed: VistaImageParams) => VistaBox | void | null | undefined;
  onImageView?: (data: VistaData, vistaView: VistaView) => void;
  onContentChange?: (content: VistaImageClone, vistaView: VistaView) => void;
  onDeactivateUi?: (names: string[], requestBy: VistaBox | null, vistaView: VistaView) => void;
  onReactivateUi?: (names: string[], requestBy: VistaBox | null, vistaView: VistaView) => void;
  onOpen?: (vistaView: VistaView) => void;
  onClose?: (vistaView: VistaView) => void;
}

Properties:

name (required) - Unique identifier for the extension
description (optional) - Human-readable description
control (optional) - Returns a custom UI control element
onInitializeImage (optional) - Hook to replace default image creation
onImageView (optional) - Triggered when navigating between images
onContentChange (optional) - Triggered when content changes
onDeactivateUi (optional) - Triggered when UI controls are deactivated
onReactivateUi (optional) - Triggered when UI controls are reactivated
onOpen (optional) - Triggered when lightbox opens
onClose (optional) - Triggered when lightbox closes

Type References:

VistaImageParams - Used in onInitializeImage
VistaData - Used in onImageView
VistaImageClone - Used in onContentChange

Control Types

VistaDefaultCtrl

Built-in control names.

type VistaDefaultCtrl = 'indexDisplay' | 'zoomIn' | 'zoomOut' | 'close' | 'description';

Advanced Types

VistaImageParams

Parameters passed to extension onInitializeImage hook.

interface VistaImageParams {
  elm: VistaParsedElm;
  pos: number;
  index: number;
  maxZoomLevel: number;
  onScale: (par: { vistaImage: VistaBox; scale: number; isMax: boolean; isMin: boolean }) => void;
  vistaView: VistaView;
  transitionState?: VistaHiresTransitionOpt;
  transitionShouldWait?: () => boolean;
}

Properties:

elm - Parsed element (VistaParsedElm)
pos - Position in the view
index - Image index
maxZoomLevel - Maximum zoom level
onScale - Callback for scale changes
vistaView - VistaView instance
transitionState - Optional transition state
transitionShouldWait - Optional transition wait function

Pointer Event Types

VistaPointer

Represents a single pointer (mouse, touch, or pen) position and movement.

type VistaPointer = {
  x: number;
  y: number;
  movementX: number;
  movementY: number;
  id: number | string;
};

Properties:

x - Current X coordinate
y - Current Y coordinate
movementX - Movement delta on X axis since last event
movementY - Movement delta on Y axis since last event
id - Unique identifier for this pointer

VistaPointerListenerArgs

Arguments passed to internal pointer listeners used by VistaPointers.

type VistaPointerListenerArgs = {
  event: 'down' | 'move' | 'up' | 'cancel';
  pointer: VistaPointer;
  pointers: VistaPointer[];
  lastPointerLen: number;
};

Properties:

event - Type of pointer event
pointer - Current VistaPointer data
pointers - Array of all active VistaPointer instances
lastPointerLen - Previous number of active pointers (for detecting pointer count changes)

VistaPointerListener

A listener function passed to VistaPointers via VistaPointerArgs.listeners or addEventListener().

type VistaPointerListener = (args: VistaPointerListenerArgs) => void;

Parameters:

args - VistaPointerListenerArgs event data

VistaExternalPointerListenerArgs

Arguments passed to external pointer listeners registered via registerPointerListener().

type VistaExternalPointerListenerArgs = {
  event: 'down' | 'move' | 'up' | 'cancel';
  pointer: VistaPointer;
  pointers: VistaPointer[];
  lastPointerLen: number;
  state: VistaState;
  hasInternalExecution: boolean;
  abortController: AbortController | null;
};

Properties:

event - Type of pointer event
pointer - Current VistaPointer data
pointers - Array of all active VistaPointer instances
lastPointerLen - Previous number of pointers (for detecting changes)
state - VistaState instance
hasInternalExecution - Whether VistaView handled this event internally
abortController - Controller for canceling operations

GitHub • npm • llms.txt • Context7