Arx Lightbox — Documentation

Installation

Link the CSS in <head>, jQuery, and the plugin just before </body>.

HTML

<link rel="stylesheet" href="css/lightbox.css">
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script src="js/lightbox.js"></script>

Basic Usage

Call .lightbox() on any link pointing to an image. The href becomes the lightbox source.

HTML

<a href="images/full.jpg">
    <img src="images/thumb.jpg" alt="A photo">
</a>

JavaScript

$('[data-lightbox]').lightbox();

Or target specific selectors directly:

JavaScript

$('a[href$=".jpg"]').lightbox();

Galleries

Group images together with the data-lightbox attribute. Elements sharing the same value are linked as a gallery — navigation arrows and a counter appear automatically.

HTML

<a href="images/01.jpg" data-lightbox="vacation">
    <img src="images/01-thumb.jpg" alt="Photo 1">
</a>
<a href="images/02.jpg" data-lightbox="vacation">
    <img src="images/02-thumb.jpg" alt="Photo 2">
</a>
<a href="images/03.jpg" data-lightbox="vacation">
    <img src="images/03-thumb.jpg" alt="Photo 3">
</a>

JavaScript

$('[data-lightbox]').lightbox();

Captions

Captions are pulled from data-lightbox-caption by default. If absent, the plugin falls back to the link's title attribute, then the alt of the inner <img>. Override with the captionAttr option.

HTML

<a href="images/photo.jpg" data-lightbox-caption="Sunset over the bay">
    <img src="images/thumb.jpg" alt="Sunset">
</a>

<!-- Custom caption attribute -->
<a href="images/photo.jpg" data-custom-caption="My caption">
    <img src="images/thumb.jpg">
</a>

JavaScript

$('a').lightbox({
    captionAttr: 'data-custom-caption'
});

Keyboard Shortcuts

All shortcuts work while the lightbox is open. Tab cycles between the close button and navigation arrows; focus is trapped inside the overlay and restored to the trigger on close.

Key	Action
`←`	Previous image
`→`	Next image
`Escape`	Close the lightbox
`Tab`	Cycle focus: close → arrows → close

Touch & Swipe

On touch devices, swipe left or right to navigate between images. On desktop, click and drag the image horizontally. Vertical scrolling is preserved — only horizontal swipes are intercepted. Disable with swipeEnabled: false or adjust sensitivity with swipeThreshold (px).

Programmatic API

Control the lightbox from JavaScript — useful for triggering from a button, after an AJAX load, or any custom interaction.

JavaScript

// Open from a temporary element
var $el = $('<a>').attr({
    href: 'images/photo.jpg',
    'data-lightbox-caption': 'Loaded dynamically'
});
$('body').append($el);
$el.lightbox({});
$el.trigger('click');
$el.remove();

// Close the lightbox
$().lightbox('close');
// or
ArxLightbox.close();

// Navigate
$().lightbox('next');  // or ArxLightbox.next()
$().lightbox('prev');  // or ArxLightbox.prev()

// Check state
$().lightbox('isOpen');  // returns true / false
ArxLightbox.isOpen();     // same

Options

Pass an object to .lightbox(options) to configure behaviour.

Option	Type	Default	Description
`groupAttr`	`string`	`data-lightbox`	Attribute used to detect gallery grouping.
`captionAttr`	`string`	`data-lightbox-caption`	Attribute used to read the caption.
`showCounter`	`boolean`	`true`	Show "3 / 8" counter for galleries.
`showArrows`	`boolean`	`true`	Show previous/next arrows for galleries.
`closeOnClick`	`boolean`	`true`	Close when clicking the background overlay.
`closeOnEsc`	`boolean`	`true`	Close on Escape key press.
`animationSpeed`	`number`	`300`	Overlay fade-in/out duration (ms).
`fadeSpeed`	`number`	`250`	Image fade-in duration (ms).
`zIndex`	`number`	`9999`	CSS z-index of the overlay.
`loop`	`boolean`	`true`	Loop gallery navigation (wrap around).
`swipeEnabled`	`boolean`	`true`	Enable swipe/drag left/right.
`swipeThreshold`	`number`	`50`	Min horizontal swipe distance to navigate (px).
`onOpen`	`function`	`null`	Callback when lightbox opens.
`onClose`	`function`	`null`	Callback when lightbox closes.
`onChange`	`function`	`null`	Callback when navigating between images.

Methods

Call methods as a string argument to .lightbox() or via the global ArxLightbox object.

Method	Usage	Description
`close`	`$().lightbox('close')`	Closes the lightbox.
`next`	`$().lightbox('next')`	Moves to the next image.
`prev`	`$().lightbox('prev')`	Moves to the previous image.
`isOpen`	`$().lightbox('isOpen')`	Returns `true` if the lightbox is currently open.

Same methods via window.ArxLightbox: ArxLightbox.close(), ArxLightbox.next(), ArxLightbox.prev(), ArxLightbox.isOpen().

Styling

All lightbox elements use CSS classes prefixed with .arx-lightbox-. Override them after importing lightbox.css to customize the look.

Class	Element	Purpose
`.arx-lightbox-overlay`	`div`	Full-screen darkened backdrop
`.arx-lightbox-container`	`div`	Centering flex wrapper
`.arx-lightbox-image`	`img`	The displayed image
`.arx-lightbox-close`	`button`	Close button (top-right)
`.arx-lightbox-arrow`	`button`	Previous / next navigation arrows
`.arx-lightbox-counter`	`div`	Gallery counter (top-left)
`.arx-lightbox-caption`	`div`	Caption text (bottom-center)
`.arx-lightbox-loader`	`div`	Loading spinner container
`.arx-lightbox-spinner`	`div`	Animated loading spinner
`.arx-lightbox-error`	`div`	Error state container
`.arx-lightbox-error-icon`	`span`	Error icon (circle + exclamation)
`.arx-lightbox-error-text`	`span`	Error message text

Download

Download individual plugin files or grab the full package as a ZIP from the Library page.

File	Description
`README.md`	Installation, usage, options, and API reference	Download
`css/lightbox.css`	Lightbox overlay, image, arrows, and spinner styles	Download
`js/lightbox.js`	jQuery plugin — all lightbox logic and API	Download