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

importNimagefrom'@neabyte/nimage'

CDN (jsDelivr/unpkg/esm.sh):

<scripttype="module">// Import runs auto-mount onceimportNimagefrom'https://cdn.jsdelivr.net/npm/@neabyte/nimage/dist/index.mjs'</script>

Or via esm.sh:

<scripttype="module">importNimagefrom'https://esm.sh/@neabyte/nimage'</script>

Or via importmap:

<scripttype="importmap">{"imports": {"@neabyte/nimage": "https://cdn.jsdelivr.net/npm/@neabyte/nimage/dist/index.mjs"}}</script><scripttype="module">importNimagefrom'@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.

<imgsrc="thumb.jpg" data-nimagedata-nimage-full="full.jpg" alt="A photo" /><scripttype="module">// Auto-mount wires the image aboveimportNimagefrom'@neabyte/nimage'</script>

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

<imgsrc="a.jpg" data-nimagedata-nimage-group="trip" data-nimage-full="a-full.jpg" alt="Day one" /><imgsrc="b.jpg" data-nimagedata-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 arrayconstviewer=Nimage.create([{imageSrc: 'a.jpg',altText: 'First'},{imageSrc: 'b.jpg',altText: 'Second'}])viewer.open(0)// Turn a container into a carouselNimage.carousel('#banner',{autoplayDelay: 4000})// Recolor the accentNimage.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.