Image Popup Viewer | NDS - Vanilla National Design System

Image Gallery

Click any thumbnail to open the full-screen viewer with zoom and navigation controls

Mountain Landscape

Forest Road

Ocean View

Valley Sunrise


<div class="nds-ipv-gallery nds-grid" style="--max-col:4;--mid-col:2;--min-col:1;">
    <div class="nds-ipv-image-card">
        <img src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=400"
            data-ipv-full="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=2000"
            alt="Mountain Landscape" class="nds-ipv-thumbnail">
        <div class="nds-ipv-image-title">Mountain Landscape</div>
    </div>

    <div class="nds-ipv-image-card">
        <img src="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=400"
            data-ipv-full="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=2000"
            alt="Forest Road" class="nds-ipv-thumbnail">
        <div class="nds-ipv-image-title">Forest Road</div>
    </div>

    <div class="nds-ipv-image-card">
        <img src="https://images.unsplash.com/photo-1472214103451-9374bd1c798e?w=400"
            data-ipv-full="https://images.unsplash.com/photo-1472214103451-9374bd1c798e?w=2000"
            alt="Ocean View" class="nds-ipv-thumbnail">
        <div class="nds-ipv-image-title">Ocean View</div>
    </div>

    <div class="nds-ipv-image-card">
        <img src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=400"
            data-ipv-full="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=2000"
            alt="Valley Sunrise" class="nds-ipv-thumbnail">
        <div class="nds-ipv-image-title">Valley Sunrise</div>
    </div>
</div>

Built-in Features

What you get out of the box with zero configuration

Auto-initialization

Any image with the nds-ipv-thumbnail class becomes clickable and opens in the full-screen viewer. No extra markup or JS calls needed. For dynamically added images, call NDS.Ipv.init().

Multi-input Zoom

Zoom into images using mouse wheel (centered on cursor position), keyboard shortcuts (+/-), pinch-to-zoom on touch devices, or the on-screen zoom buttons. Supports 0.1x to 10x magnification.

Drag to Pan

Click and drag on desktop or swipe on touch devices to pan around zoomed images. Double-click or double-tap resets the view to the original position and zoom level.

Gallery Navigation

When multiple thumbnails share a gallery container, arrow buttons and keyboard left/right keys navigate between images. An image counter displays the current position.

Keyboard Controls

Full keyboard support: Escape closes the viewer, +/- adjusts zoom, 0 resets the view, H toggles the control UI, and arrow keys navigate between images.

Touch Gestures

Pinch-to-zoom with two fingers centers on the gesture midpoint. Single-finger drag pans the image. All gestures work alongside on-screen controls on mobile.

Distraction-free Mode

Press H or tap the toggle button to hide all controls, navigation, and overlays for a clean viewing experience. Toggle again to restore the full UI.

Adaptive Image Loading

Thumbnails load at a small size for fast page rendering, then the full-resolution image loads on demand when opened. A loading spinner displays while the full image is fetched.

Usage Guidelines

When and how to use the image popup viewer effectively

Best Practices

Use the image popup viewer for any content where users need to inspect image details: product photos, maps, infographics, architectural plans, or document scans. The zoom and pan controls let users explore at their own pace.
Use the gallery layout (nds-ipv-gallery) to group related images with shared navigation. Users can browse through all images with arrow keys or on-screen buttons without closing and reopening.
Use standalone thumbnails outside a gallery when images are independent of each other. Each nds-ipv-thumbnail opens its own viewer without gallery navigation.
Do not use the image popup viewer for decorative or background images that don't benefit from close inspection. Only apply it to images where zoom and detail matter to the user.
Do not use this component for modal dialogs with mixed content. Use Modal instead when you need text, forms, or actions alongside an image.
Always provide a data-ipv-full attribute pointing to a high-resolution version of the image. Without it, the viewer falls back to the thumbnail src, which may look blurry when zoomed.
Keep thumbnail images small (400px wide) for fast page load. The full-resolution image loads on demand only when the user opens the viewer.
Write descriptive alt text on every thumbnail. The viewer inherits this for accessibility.
Add nds-ipv-image-title below thumbnails in galleries to give users context before they open the viewer.

Data Attributes

Attribute	Description
`data-ipv-full`	Set on the thumbnail `<img>` to specify the full-resolution image URL loaded when the viewer opens.

JavaScript API

The NDS.Ipv API controls initialization and programmatic access. The viewer auto-initializes on page load. For dynamically added thumbnails, call NDS.Ipv.init() to re-scan the page.


// ── Initialization ──────────────────────────────────
// All thumbnails auto-initialize on page load
NDS.Ipv.init();

// Create and get the viewer instance
var viewer = NDS.Ipv.create();

// Access the existing instance directly
var viewer = window.ndsIPV;

// ── Instance Methods ────────────────────────────────
// Open the viewer for a specific thumbnail element
viewer.open(thumbnailElement);

// Close the viewer
viewer.close();

// Navigate between images in a gallery
viewer.showPrev();
viewer.showNext();

// Reset zoom and pan to defaults
viewer.resetTransform();

// Toggle UI controls visibility (distraction-free mode)
viewer.toggleUI();

// ── Keyboard Shortcuts ──────────────────────────────
// Escape       Close the viewer
// + or =       Zoom in (1.5x per press)
// -            Zoom out (1.5x per press)
// 0            Reset zoom and position
// H            Toggle UI visibility
// ArrowLeft    Previous image in gallery
// ArrowRight   Next image in gallery