repository·master·Indexed 20 days ago
https://github.com/nicolafranchini/venoboxVenoBox is a responsive JavaScript lightbox plugin for displaying images, inline content, iFrames, and videos in a modal window. Version 2.2.0 features touch-swipe gallery support, intelligent scaling for small devices, and a comprehensive API for programmatic control. It can be installed via npm or Composer and supports both vanilla JavaScript and jQuery environments.
If you are not using a package manager, download the latest release or use jsDelivr.
<head>.</body> tag.<!-- In <head> -->
<link rel="stylesheet" href="venobox/dist/venobox.min.css" />
<!-- Before </body> -->
<script src="venobox/dist/venobox.min.js"></script>To use VenoBox, follow these two steps:
venobox) and set the href attribute to the large media file (image, video, etc.).VenoBox class and provide a selector option that matches your HTML class.This plugin is suitable for images, inline contents, iFrames, and videos. It features a responsive design that preserves image height if the image is taller than the window to avoid microscopic resizing on small devices.
<!-- 1. HTML Structure -->
<a class="venobox" href="image01-big.jpg">
<img src="image01-small.jpg" alt="image alt"/>
</a>// 2. JavaScript Initialization
import VenoBox from 'venobox';
new VenoBox({
selector: '.venobox'
});VenoBox requires its stylesheet to be included in your project. You can import it directly into your CSS entry point or link it via an HTML <link> tag.
Via CSS @import:
@import "venobox/dist/venobox.min.css";Via HTML link:
<link rel="stylesheet" href="node_modules/venobox/dist/venobox.min.css">You can install VenoBox using either npm for JavaScript environments or Composer for PHP environments.
npm install venobox
# or
composer require nicolafranchini/venoboxTo use VenoBox, instantiate the VenoBox constructor with an options object. By default, it searches for elements matching the .venobox selector and attaches click listeners to open them in a lightbox. You can also provide a custom selector or use the jQuery plugin bridge if jQuery is available in your environment.
import VenoBox from './venobox.esm.js';
// Initialize with default settings
const vbox = new VenoBox();
// Initialize with custom settings
const vbox = new VenoBox({
selector: '.my-custom-selector',
autoplay: true
});The VenoBox constructor accepts an options object to override default behaviors. Key configuration options include:
| Option | Default | Description |
|---|---|---|
selector | '.venobox' | CSS selector for the trigger elements. |
autoplay | false | Whether videos should autoplay. |
bgcolor | '#fff' | Background color of the content. |
border | '0' | Border thickness. |
customClass | false | A custom CSS class to add to the overlay. |
infinigall | false | Whether the gallery should loop infinitely. |
navigation | true | Enable/disable next/prev buttons. |
navKeyboard | true | Enable/disable keyboard navigation. |
navTouch | true | Enable/disable touch/swipe navigation. |
navSpeed | 300 | Transition speed in ms. |
numeration | false | Show '1 / 5' style numbering. |
overlayClose | true | Allow closing by clicking the overlay. |
overlayColor | 'rgba(23,23,23,0.95)' | Color of the backdrop. |
popup | false | CSS selector for an element to open immediately on init. |
ratio | '16x9' | Aspect ratio: '1x1', '4x3', '16x9', or '21x9'. |
share | false | Enable share/download/copy link tools. |
shareStyle | 'pill' | Style for share tools: 'bar', 'block', 'pill', or 'transparent'. |
spinner | 'bounce' | Preloader type: 'plane', 'chase', 'bounce', 'wave', 'pulse', 'flow', 'swing', 'circle', 'circle-fade', 'grid', 'fold', 'wander'. |
spinColor | '#d2d2d2' | Color of the spinner. |
titleattr | 'title' | Attribute used to extract the title. |
titlePosition | 'top' | Position of the title: 'top' or 'bottom'. |
titleStyle | 'bar' | Style for title: 'bar', 'block', 'pill', or 'transparent'. |
toolsBackground | '#1C1C1C' | Background color for navigation/share tools. |
toolsColor | '#d2d2d2' | Color for navigation/share tools. |
fitView | false | Whether to use fit-view logic for content. |
initialScale | 0.9 | Initial scale of the content during transition. |
transitionSpeed | 200 | Transition speed in ms. |
If jQuery is loaded in your project, VenoBox extends the jQuery prototype, allowing you to initialize it using the .venobox() method on a jQuery collection.
$('.venobox').venobox({
autoplay: true,
spinner: 'chase'
});The VenoBox instance returned by the constructor provides methods to programmatically control the lightbox:
open(obj): Opens a specific element (the obj must be a DOM element).close(): Closes the currently open lightbox.next(): Navigates to the next item in the current gallery.prev(): Navigates to the previous item in the current gallery.Access the current configuration via venobox.settings.
const vbox = new VenoBox();
// Later in your code...
vbox.open(document.querySelector('.some-link'));
// Or control navigation
vbox.next();VenoBox provides several callback functions within the options object to hook into the lightbox lifecycle. These allow you to run custom logic at specific stages:
onInit(plugin): Called when the plugin is initialized. Receives the plugin instance.onPreOpen(item): Called before an item opens. Return false to prevent opening.onPostOpen(item, gallIndex, thenext, theprev): Called after the lightbox is fully open.onPreClose(item, gallIndex, thenext, theprev): Called before closing. Return false to prevent closing.onNavComplete(item, gallIndex, thenext, theprev): Called after navigation between gallery items is complete.onContentLoaded(newcontent): Called when new content is injected into the lightbox.Note: item refers to the DOM element being opened.
new VenoBox({
onPreOpen: function(item) {
console.log('Opening:', item);
return true; // return false to cancel
},
onPostOpen: function(item, gallIndex) {
console.log('Gallery index:', gallIndex);
}
});