Nimage is a zero-dependency image viewer and carousel written in vanilla TypeScript. It scans your page for tagged images, groups them, and opens a fullscreen viewer with hover previews, pinch zoom, slideshows, thumbnails, and keyboard control. It also ships a standalone banner carousel that can hand its slides to the same viewer.
<img src="thumb.jpg" data-nimage data-nimage-full="full.jpg" alt="A photo">
<script type="module">
// Import runs auto-mount once
import Nimage from '@neabyte/nimage'
</script>That is the whole setup. On load Nimage calls mount() for you. It scans every img[data-nimage], then wires the click, hover, and keyboard behaviour. No init call is required.
Nimage is a single frozen object with five methods. Import the default export and call what you need.
import Nimage from '@neabyte/nimage'| 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 |
Every argument named root defaults to document. mount runs automatically once on load, so most pages only ever call theme or carousel by hand.
When the module loads in a browser it checks document.readyState. If the document is still loading it waits for DOMContentLoaded, otherwise it mounts right away.
if (typeof document !== 'undefined') {
if (document.readyState === 'loading') {
// Wait until the DOM is ready
document.addEventListener('DOMContentLoaded', () => {
Nimage.mount()
})
} else {
// Document already parsed, mount now
Nimage.mount()
}
}The typeof document guard keeps the module safe to import in a non-DOM runtime without throwing.
| Piece | What it does | Doc |
|---|---|---|
| Viewer | The fullscreen lightbox with groups, zoom, slideshow, thumbnails, hover | viewer |
| Carousel | A standalone slider with arrows, dots, autoplay, swipe, optional lightbox | carousel |
| Theme | Ten CSS variables you can override at runtime with theme() |
theming |
| Data hooks | The data-* attributes that drive markup-only setup |
data attributes |
| Need | Where |
|---|---|
| Open images from plain HTML | getting started |
| Group images so one click pages the set | data attributes |
| Build a viewer from a JavaScript array | viewer |
| Add a banner slider | carousel |
| Send carousel slides to the lightbox | carousel |
| Recolor the viewer | theming |
| Learn the shortcuts and touch gestures | keyboard and gestures |
| Read the exported type shapes | types |
- Getting Started - install, import, auto-mount, the first gallery
- Viewer - the lightbox, its options, instance methods, and grouping
- Carousel - the slider, its options, data attributes, and lightbox handoff
- Theming -
theme(), the ten variables, and value validation - Data Attributes - every
data-*hook for markup-only setup - Keyboard and Gestures - the full key map and touch gestures
- Types - exported interface and type definitions
Every type Nimage accepts or returns lives in src/types.ts. The types page mirrors them, and that file is the authoritative definition.