Image Gallery
Click any thumbnail to open the full-screen viewer with zoom and navigation controls
// Auto-initializes on page load; call again after dynamic thumbnail injection
NDS.Ipv.init();
// Re-scan for new thumbnails added at runtime
NDS.Ipv.reinit();
// Initialize and get the viewer instance
var viewer = NDS.Ipv.create();
// Open programmatically, close, and tear down
viewer.open(document.querySelector('.nds-ipv-thumbnail'));
viewer.close();
viewer.destroy();
Built-in Features
What you get out of the box with zero configuration
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().
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.
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.
Every thumbnail on the page joins one navigable gallery. Arrow buttons and the left/right keys move between images, and a counter shows the current position. Controls hide automatically when a page has only one image.
Thumbnails are reachable with Tab and open with Enter or Space. Inside the viewer, Escape closes, +/- adjusts zoom, 0 resets the view, H toggles the controls, and arrow keys move between images.
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.
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.
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.
The viewer opens as a focus-trapped dialog: keyboard focus stays within it while open, and returns to the thumbnail you opened it from when it closes.
Control labels and on-screen instructions follow the page language automatically, with Arabic and English provided out of the box.
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.
- Every
nds-ipv-thumbnailon a page joins one shared gallery: opening any image lets users move through the rest with the arrow keys or on-screen buttons. Keep related images on the same page so navigation feels coherent. - Navigation controls appear only when a page has more than one thumbnail. For a single standalone image, the viewer opens with zoom and pan but no prev/next controls.
- 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-fullattribute 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
alttext on every thumbnail. The viewer reuses it for the full-size image, and it doubles as the accessible name when users reach the thumbnail by keyboard. - Thumbnails are keyboard-operable out of the box: Tab focuses them, Enter or Space opens the viewer, and focus returns to the thumbnail on close. Avoid adding custom click-only handlers that bypass this.
- Add
nds-ipv-image-titlebelow thumbnails in galleries to give users context before they open the viewer.
Modifier Classes
| Class | Description |
|---|---|
nds-ipv-thumbnail | Required on the <img> that opens the viewer. |
nds-ipv-gallery | Optional grid wrapper for image items. Combine with nds-grid and the --max-col / --mid-col / --min-col variables to set columns. |
nds-ipv-image-item | Optional grid cell grouping an image card with its caption below. |
nds-ipv-image-card | Optional frame around the thumbnail; hosts the showZoom badge. |
nds-ipv-image-title | Optional caption placed below the image card. |
showZoom | Add to nds-ipv-image-card to display a zoom-affordance badge in the corner of the thumbnail. |
Data Attributes
| Attribute | Description |
|---|---|
data-ipv-full | Set on the thumbnail <img> to specify the full-resolution image URL loaded when the viewer opens. |
data-src | Fallback full-size source used when data-ipv-full is absent (supports lazy-loading setups). The thumbnail's own src is the final fallback. |
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() or NDS.Ipv.reinit() to re-scan the page.