Nimage

Drop-in lightbox that transforms tagged images into immersive galleries

Features

• Zero dependencies - No external packages required.
• Auto mount - Tag images with data-nimage and the viewer wires itself on load.
• Grouped galleries - Share a group so one click pages the whole set.
• Hover preview - A floating popover follows the cursor before you click.
• Zoom and pan - Wheel, double-click, keyboard, and pinch zoom with drag panning.
• Slideshow - Timed autoplay with a progress bar and loop control.
• Thumbnails - A scrollable strip that centers the active image.
• Keyboard and touch - Full arrow, Esc, Space, F, and zoom keys, plus swipe and pinch.
• Carousel - A standalone banner slider with arrows, dots, autoplay, and lightbox.
• Theming - Recolor the whole UI at runtime through ten CSS variables.
• Accessible - Focus trap, focus restore, and a live region on the counter.

Installation

[!NOTE] Prerequisites: For npm use Node.js (e.g. nodejs.org).

npm:

npm install @neabyte/nimage

import Nimage from '@neabyte/nimage'

CDN (jsDelivr/unpkg/esm.sh):

<script type="module">
// Import runs auto-mount once
import Nimage from 'https://cdn.jsdelivr.net/npm/@neabyte/nimage/dist/index.mjs'
</script>

Or via esm.sh:

<script type="module">
import Nimage from 'https://esm.sh/@neabyte/nimage'
</script>

Or via importmap:

<script type="importmap">
{
  "imports": {
    "@neabyte/nimage": "https://cdn.jsdelivr.net/npm/@neabyte/nimage/dist/index.mjs"
  }
}
</script>
<script type="module">
import Nimage from '@neabyte/nimage'
</script>

Quick Start

Tag any image with data-nimage. On load Nimage scans the page, wires the click, hover, and keyboard behaviour, and opens a fullscreen viewer when clicked.

<img src="thumb.jpg" data-nimage data-nimage-full="full.jpg" alt="A photo" />
<script type="module">
// Auto-mount wires the image above
import Nimage from '@neabyte/nimage'
</script>

Give several images the same data-nimage-group and one click pages through the whole set.

<img src="a.jpg" data-nimage data-nimage-group="trip" data-nimage-full="a-full.jpg" alt="Day one" />
<img src="b.jpg" data-nimage data-nimage-group="trip" data-nimage-full="b-full.jpg" alt="Day two" />

Public API

Nimage is a single frozen object with five methods.

| Method | Returns | Description | | ------------------------------- | ---------- | ----------------------------------------------------------- | | mount(root?) | void | Scan a root for tagged images and carousels, then wire them | | scan(root?) | Viewer | Scan a root for tagged images only, then return the viewer | | create(imageList, options?) | Viewer | Build a viewer from a manual image list with no DOM scan | | carousel(container, options?) | Carousel | Turn a container into a banner carousel | | theme(theme) | void | Recolor the whole UI at runtime through CSS variables |

// Build a viewer from an array
const viewer = Nimage.create([
  { imageSrc: 'a.jpg', altText: 'First' },
  { imageSrc: 'b.jpg', altText: 'Second' }
])
viewer.open(0)

// Turn a container into a carousel
Nimage.carousel('#banner', { autoplayDelay: 4000 })

// Recolor the accent
Nimage.theme({ accentColor: '#e11d48' })

Read docs/README.md for full documentation.

Build

npm build (bundles to dist/):

npm run build

Testing

Type check - format, lint, and type-check:

deno task check

License

This project is licensed under the MIT license. See the LICENSE file for details.