# VenoBox: a lightbox that does not shrink a tall image into a postage stamp
> VenoBox is a dependency-free vanilla JavaScript modal and gallery plugin for images, videos, iframes and inline content, and its distinguishing decision is to size the image to the window width and let a tall image keep its height and scroll. Version 2 is ESM only and the last npm release was in 2023.
**nicolafranchini/VenoBox** — Responsive Vanilla JS lightbox plugin, suitable for images, videos, iFrames, inline contents
- Repository: https://github.com/nicolafranchini/VenoBox
- Website: https://veno.es/venobox/
- Stars: 716 · Forks: 167
- Language: JavaScript
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/nicolafranchini-venobox
## The sizing rule is the whole argument for it
VenoBox is a responsive modal window JavaScript plugin with a touch swipe gallery, and the README opens with what it considers the big difference compared to many other plugins.
The library calculates the max width of the image displayed and preserves its height if it is taller than the window. The consequence, spelled out in the same sentence, is that on small devices you can scroll down the content, which avoids vertical microscopic resized images.
That is a specific and defensible position on responsive behaviour. The common lightbox approach fits the image entirely inside the viewport, which for a tall image on a phone means scaling it down until it is a strip, and a strip is unreadable. VenoBox instead fits the width and lets the height overflow, so you scroll. The tradeoff is a modal whose content can be taller than the screen, which is a scrolling surface inside a modal, and that is a design decision rather than a technical limit.
The package is MIT licensed, the primary language is JavaScript, the default branch is master, and the last push was on 2026-10-18. The release history shows 1.9.4 for the jQuery build in August 2018 and 2.2.0 for VenoBox 2 in November 2023, so the vanilla line is where the work is and the jQuery one is a frozen legacy branch.
The keyword list in the manifest is a good summary of the scope: lightbox, modal, gallery, responsive, vanilla, no-jquery, touch and swipe.
## Installing it, and the CSS that has to be loaded separately
There are two package managers, which is unusual for a front end library and reflects that the author also ships a Composer package. On npm it is npm install venobox, and on Packagist it is composer require nicolafranchini/venobox, with a composer.json in the repository root.
The JavaScript is imported as a module:
```code
import VenoBox from 'venobox';
```
The CSS is separate, and the README gives two ways to include it. Via an import in your CSS entry point:
```code
@import "venobox/dist/venobox.min.css";
```
or via a link tag in the HTML head:
```html
```
The stylesheet is not injected by the script, which is the right call for anyone who has fought a library that appends style tags to the head, and it does mean a missing stylesheet gives you an unstyled modal rather than a broken one.
The manifest confirms the layout. The style field points at dist/venobox.min.css, the main field at dist/venobox.min.js, the module field at the ESM source in src, and the browser field at the minified bundle. The type is module, so the package is ESM only, and the build scripts are a CSS step using clean-css with a source map and inline sources plus a JavaScript step using rollup, with a watch mode for development.
The build tools are three dev dependencies and nothing else: rollup with the terser plugin, clean-css-cli, and that is the entire list. There are no runtime dependencies at all, which is the point of the package being called a vanilla JavaScript plugin.
## Using it in a bundler and in plain HTML
For a static site with no build step, the README gives the CDN route. You download the latest release or get the sources from jsDelivr, put the stylesheet into the head to load the CSS:
```html
```
and include the script near the end of your pages, right before the closing body tag:
```html
```
The placement instruction is not cosmetic. The script is loaded at the end of the document so the elements it scans already exist, and the CSS in the head so the modal is styled before it appears.
In a bundler, the usage is a class on the links you want to be lightbox triggers, and an initialisation call:
```html
```
```javascript
new VenoBox({
selector: '.venobox'
});
```
The pattern is worth naming because it is the same in every gallery library: the link href holds the full-size asset and the img src holds a thumbnail, and the library intercepts the click. That means your markup degrades gracefully, since without JavaScript the link still opens the large image.
The options object is a plain object passed to the constructor, and the selector is what tells it which links to bind to. The full documentation is at the project site, venobox on veno.es.
The scope, from the description and the keywords, is images, inline contents, iframes and videos, with a touch swipe gallery for the latter. The README does not enumerate the option names, so the options surface is the part you would need to check in the documentation or the source.
## What the repository looks like, and the licensing picture
The repository is small, in the way a focused front end library usually is. At the top level there is a .gitignore, a CHANGELOG.md, the LICENSE, the README, a composer.json, a dist/ directory, a package-lock.json, the package.json, a rollup.config.js and a src/ directory.
So there are two build outputs in dist/, the minified script and the minified stylesheet, alongside the unminified CSS, and the source is a single ESM entry point referenced by the module field. The CHANGELOG is present, which for a project whose last npm release was in November 2023 tells you what changed in the intervening years of work on the master branch, and those changes are not in a published version.
The licensing is a single MIT notice in the README, released under the MIT License, and there is a LICENSE file. The composer.json exists so the package can also be pulled into a PHP project, which is a slightly unusual route for a JavaScript library but it makes sense for the author's audience, and it is how the static HTML usage in the README stays plausible for people who do not run a JavaScript build.
The homepage is veno.es/venobox, and there is a demo at the same site showing the plugin in use. The author is Nicola Franchini, and the bugs and homepage links in the manifest point at the same domain rather than at a separate issue tracker, which tells you the repository is a home for the library rather than a busy community project.
## Where VenoBox is the wrong choice
The first wrong case is a build that still needs jQuery. There was a 1.9.4 jQuery release, and it is a frozen branch with its own tag, so a legacy site that loads jQuery and expects the old plugin API is depending on code that stopped changing in 2018. The vanilla line is the one to use, and it means dropping the jQuery dependency or accepting two different eras of the same library in one project.
The second is a project that needs typed options and a plugin ecosystem. The options are an untyped plain object, the documented surface is small, and there is no TypeScript declaration file in the repository. If your team wants the compiler to check the configuration, you are writing the types yourself.
The third is a gallery with heavy customisation needs. A modal with a preset layout, a fixed style and a swipe gesture covers the common case well. If you need a themeable chrome, per-image captions with credit lines, or a gallery that integrates with a router so that each image has its own URL, that is a different library with more surface.
The fourth is a project with a strict support policy. The last published npm version is 2.2.0 from November 2023, and the branch is still being worked on but the release line is not moving. For a library that is only a few kilobytes, that is a small risk, but it is a real one, and the CHANGELOG is where you would look to see how much has changed since the published version.
The alternative worth weighing is a photo gallery framework, which is a bigger dependency and a different commitment, or the native dialog element with a small script of your own, which gives you full control and the scroll behaviour VenoBox is built around.
## Conclusion
Adopt VenoBox if you need a lightbox for images, video or embedded content and you would rather not add a jQuery-era gallery library to a modern build, since the package is ESM, has no runtime dependencies and is a few kilobytes of JavaScript plus a stylesheet. Keep away if you need typed options, a plugin ecosystem or a maintained jQuery build, because the jQuery variant stopped in 2018 and the vanilla line stopped in 2023. Before you pin a version, check how you are loading the CSS, because the stylesheet is shipped separately from the script and the documented paths differ between a bundler setup and a plain HTML page.
## FAQ
### What is VenoBox and what does it do differently from other lightbox plugins?
It is a responsive modal window and touch swipe gallery in vanilla JavaScript for images, inline contents, iframes and videos. The stated difference is that it calculates the max width of the displayed image and preserves its height when it is taller than the window, so on small devices you scroll the content instead of getting a vertically tiny resized image.
### How do I install and initialise VenoBox?
Install it with npm install venobox or composer require nicolafranchini/venobox, import the module with import VenoBox from 'venobox', include the stylesheet separately, then create the instance with new VenoBox and a selector such as '.venobox' pointing at the links you want as triggers.
### How do I load the VenoBox stylesheet?
Separately from the script. Either import it in your CSS entry point with @import "venobox/dist/venobox.min.css"; or add a link tag in the HTML head, which for a plain HTML page is the link rel="stylesheet" href="venobox/dist/venobox.min.css" form.
### Does VenoBox have any runtime dependencies?
No. The manifest lists only three dev dependencies, rollup with the terser plugin, clean-css-cli and nothing else, and the keywords include no-jquery and vanilla. The jQuery build was a separate earlier line, version 1.9.4 from 2018, and the vanilla version 2 line is the current one.
## Sources
- [License: MIT](https://github.com/nicolafranchini/VenoBox/blob/master/LICENSE)
- [nicolafranchini/VenoBox on GitHub](https://github.com/nicolafranchini/VenoBox)
- [Project website](https://veno.es/venobox/)
- [README](https://github.com/nicolafranchini/VenoBox/blob/master/README.md)
- [Releases](https://github.com/nicolafranchini/VenoBox/releases)
---
Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nicolafranchini-venobox
