VistaView Class

The VistaView class is the core controller that manages the entire lifecycle of the lightbox viewer. Each instance represents a lightbox that can be opened, navigated, and controlled programmatically.

Overview

VistaView orchestrates all aspects of the lightbox experience:

• Instance Management: Ensures only one lightbox is active at a time via GlobalVistaState
• Image Navigation: Handles next/prev navigation with smooth transitions and rapid-swap optimization
• UI Controls: Manages zoom, close, and navigation buttons
• Event Coordination: Integrates pointer events, keyboard shortcuts, and extension hooks
• State Management: Tracks current index, zoom level, and UI activation state
• Extension Integration: Calls extension lifecycle hooks at key moments

Constructor

new VistaView(elements: string | VistaImgConfig[], options?: VistaOpt)

Creates a new VistaView instance.

Parameters:

• elements: Either a CSS selector string or an array of image configurations
• options: Optional configuration object (see VistaOpt)

Example:

// Using CSS selector
const viewer = new VistaView('.gallery-item', {
  maxZoomLevel: 3,
  preloads: 2,
});

// Using configuration array
const viewer = new VistaView([
  { src: 'image1.jpg', alt: 'First image' },
  { src: 'image2.jpg', alt: 'Second image' },
]);

Public Properties

options

options: VistaOpt;

The merged configuration options for this instance. Combines user-provided options with DefaultOptions.

See VistaOpt for complete type definition.

state

state: VistaState;

The current state manager containing:

• currentIndex: Current image index
• elmLength: Total number of images
• zoomedIn: Whether the current image is zoomed
• extensions: Set of registered extensions
• children: Current DOM elements and VistaBox instances
• abortController: For canceling transitions

See VistaState for complete documentation.

imageContainer

imageContainer: HTMLElement | null;

Reference to the DOM element containing the image elements. null when the lightbox is closed.

externalPointerListener

externalPointerListener: ((e: VistaExternalPointerListenerArgs) => void)[]

Array of external pointer event listeners registered via registerPointerListener(). Used by extensions to hook into pointer events.

See VistaExternalPointerListenerArgs for the event argument type.

Public Methods

open()

open(startIndex?: number): void

Opens the lightbox at the specified image index.

Parameters:

• startIndex: The index of the image to display first (default: 0)

Behavior:

• Prevents opening if another VistaView instance is already open
• Prevents body scrolling
• Creates and injects the lightbox DOM structure
• Sets up event handlers and keyboard listeners
• Calls onOpen event callback and extension hooks
• Supports negative indices and values beyond the array length (wraps around)

Example:

const viewer = new VistaView('.gallery-item');
viewer.open(2); // Opens at the third image

close()

close(animate?: boolean): Promise<void>

Closes the lightbox and cleans up resources.

Parameters:

• animate: Whether to animate the close transition (default: true)

Behavior:

• Waits for close animation to complete (if animate is true)
• Removes DOM elements and event handlers
• Destroys all VistaBox instances
• Restores body scrolling
• Calls onClose event callback and extension hooks
• Resets GlobalVistaState

Example:

// Close with animation
await viewer.close();

// Close immediately without animation
await viewer.close(false);

destroy()

destroy(): void

Completely destroys the VistaView instance and removes all event listeners.

Behavior:

• Closes the lightbox without animation
• Removes click listeners from trigger elements
• Clears external pointer listeners
• Cannot be reopened after destruction

Example:

viewer.destroy();
// viewer is now unusable

next()

next(): void

Navigates to the next image in the sequence.

Behavior:

• Wraps around to the first image after the last one
• Triggers transition animation
• Calls onImageView event callback

Example:

viewer.next();

prev()

prev(): void

Navigates to the previous image in the sequence.

Behavior:

• Wraps around to the last image when at the first one
• Triggers transition animation
• Calls onImageView event callback

Example:

viewer.prev();

view()

view(index: number, via?: { next: boolean; prev: boolean }): void

Jumps to a specific image by index.

Parameters:

• index: The target image index
• via: Optional object indicating navigation direction (used internally)

Behavior:

• Supports negative indices and values beyond array length (wraps around)
• Aborts any in-progress transition
• Calls onImageView event callback
• Handles rapid navigation with optimized transitions

Example:

viewer.view(5); // Jump to 6th image
viewer.view(-1); // Jump to last image

zoomIn()

zoomIn(): void

Zooms in on the current image by a factor of 1.68x.

Behavior:

• Respects maxZoomLevel option
• Throttled to prevent excessive calls (222ms)
• Disables zoom-in button when at maximum zoom
• Can be disabled via deactivateUi(['zoomIn'])

Example:

viewer.zoomIn();

zoomOut()

zoomOut(): void

Zooms out of the current image by a factor of 0.68x.

Behavior:

• Returns to minimum zoom (fit to viewport)
• Throttled to prevent excessive calls (222ms)
• Disables zoom-out button when at minimum zoom
• Can be disabled via deactivateUi(['zoomOut'])

Example:

viewer.zoomOut();

getCurrentIndex()

getCurrentIndex(): number

Returns the current image index.

Returns: The zero-based index of the currently displayed image, or -1 if closed.

Example:

const index = viewer.getCurrentIndex();
console.log(`Viewing image ${index + 1}`);

reset()

reset(): void

Recalculates the image list and reattaches click listeners.

Behavior:

• Queries the DOM for elements matching the selector (if using string selector)
• Updates state.elmLength
• Removes and re-adds click event listeners

Use Case: Call this if the DOM has changed (elements added/removed) and you need to update the gallery.

Example:

// After dynamically adding more images to the page
document.querySelector('.gallery').innerHTML += '<a href="new.jpg" class="gallery-item">New</a>';
viewer.reset();

qs()

qs<T extends HTMLElement>(selector: string): T | null

Queries for an element within the lightbox root element.

Parameters:

• selector: CSS selector string

Returns: The first matching element or null

Example:

const closeButton = viewer.qs<HTMLButtonElement>('.vvw-close');

qsOrigin()

qsOrigin<T extends NodeListOf<HTMLElement>>(selector: string): T

Queries for elements in the document (not limited to lightbox root).

Parameters:

• selector: CSS selector string

Returns: NodeList of matching elements

Example:

const galleryItems = viewer.qsOrigin<NodeListOf<HTMLAnchorElement>>('.gallery-item');

registerPointerListener()

registerPointerListener(listener: (e: VistaExternalPointerListenerArgs) => void): void

Registers an external pointer event listener.

Parameters:

• listener: Function that receives VistaExternalPointerListenerArgs pointer event data

Use Case: Extensions can use this to respond to pointer events without directly managing event handlers.

Example:

viewer.registerPointerListener((e) => {
  console.log('Pointer event:', e.event, e.pointer);
  console.log('Active pointers:', e.pointers.length);
});

deactivateUi()

deactivateUi(names: string[], requestBy?: VistaBox): void

Temporarily disables UI controls.

Parameters:

• names: Array of control names to disable (e.g., ['zoomIn', 'zoomOut'])
• requestBy: Optional VistaBox instance making the request

Behavior:

• Sets disabled attribute on specified buttons
• Notifies extensions via onDeactivateUi hook
• Automatically reactivated before navigation or transitions

Example:

// Disable zoom during a custom animation
viewer.deactivateUi(['zoomIn', 'zoomOut']);

Related

• Main Function - The vistaView() function that creates VistaView instances
• VistaOpt - Configuration options type
• Event Callbacks - Events fired during lifecycle
• Lifecycle Functions - Customizable lifecycle hooks

Tip

Use the vistaView() function (lowercase ‘v’) for creating instances. The VistaView class (capital ‘V’) is primarily used for TypeScript type imports in extensions and callbacks.