Lightbox
Accessible lightbox for images, videos, and elements.
Demos
Basic
Open an image in a lightbox.
<!-- Demo coming soon -->import { Lightbox, Utils } from 'Formstone';
Utils.ready(() => {
// Demo coming soon
});/* Demo coming soon */Options
Set instance options by passing a valid object at initialization, or to the public .defaults() method. Custom options for a specific instance can also be set by attaching a data-lightbox-options attribute containing a properly formatted JSON object to the target element.
| Name | Type | Default | Description |
|---|---|---|---|
customClass |
string |
'' |
Custom CSS class for lightbox dialog |
direction |
string |
document.dir |
Content direction (ltr, rtl) |
fileTypes |
RegExp |
/\.(jpg\|sjpg\|jpeg\|png\|gif\|webp)/i |
Supported image file extensions |
label |
string |
'Gallery' |
Accessibility label |
ordinal |
boolean |
true |
Show gallery position indicator |
threshold |
number |
50 |
Swipe threshold in pixels |
templates |
object |
... |
HTML templates for UI components |
videoProviders |
object |
... |
Video provider patterns and formatters |
Data attributes provide configuration options and can be set directly on the target element.
| Name | Type | Description |
|---|---|---|
data-lightbox-options |
string (JSON) |
JSON encoded object containing instance options |
data-lightbox-gallery |
string |
Gallery group identifier for navigation |
data-lightbox-type |
string |
Force content type: 'image', 'video', 'element', or 'url' |
data-lightbox-caption |
string |
Caption text to display |
Methods
Methods are publicly available to all active instances, unless otherwise stated.
| Name | Description |
|---|---|
.close() |
Closes active lightbox instance |
.construct() |
Initializes Lightbox plugin on target elements |
.defaults() |
Sets default options for future Lightbox instances |
.destroy() |
Removes plugin and all related data |
.jump() |
Jumps to specific gallery index |
.next() |
Advances to next gallery item |
.open() |
Opens lightbox at specified index |
.previous() |
Goes back to previous gallery item |
.close()
Closes active lightbox instance.
Returns
| Type | Description |
|---|---|
Promise |
Promise that resolves when close transition completes |
Examples
el.Lightbox.close();.construct()
Initializes Lightbox plugin on target elements.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
selector |
string (required) |
'' |
Selector string to target |
options |
object (optional) |
{} |
Object containing instance options |
Returns
| Type | Description |
|---|---|
NodeList |
NodeList of target elements |
Examples
let targets = Lightbox.construct('.js-lightbox');let targets = Lightbox.construct('.js-lightbox', {
customClass: 'photo-gallery',
threshold: 100
});.defaults()
Sets default options for future Lightbox instances.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
options |
object (required) |
{} |
Object containing default options |
Examples
Lightbox.defaults({
customClass: 'my-lightbox',
threshold: 100
});.destroy()
Removes plugin and all related data.
Examples
el.Lightbox.destroy();.jump()
Jumps to specific gallery index.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
index |
number (required) |
0 |
Target index |
Examples
el.Lightbox.jump(2);.next()
Advances to next gallery item.
Examples
el.Lightbox.next();.open()
Opens lightbox at specified index.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
index |
number (optional) |
undefined |
Starting index |
Examples
el.Lightbox.open();el.Lightbox.open(2);.previous()
Goes back to previous gallery item.
Examples
el.Lightbox.previous();Events
Events are triggered on the window object.
| Name | Description |
|---|---|
lightbox:open |
Lightbox opened |
lightbox:close |
Lightbox closed |
Styles
CSS custom properties are used to modify default styles.
| Property | Default | Description |
|---|---|---|
--fs-lightbox-duration |
0.25s |
Lightbox transition duration |
--fs-lightbox-timing |
linear |
Lightbox transition timing |
--fs-lightbox-overlay-bg |
rgba(0, 0, 0, 0.9) |
Overlay background color |
--fs-lightbox-loading-color |
#fff |
Loading spinner color |
--fs-lightbox-loading-size |
40px |
Loading spinner size |
--fs-lightbox-loading-spread |
5px |
Loading spinner thickness |
--fs-lightbox-loading-duration |
0.75s |
Loading spinner animation duration |
--fs-lightbox-item-duration |
0.25s |
Content transition duration |
--fs-lightbox-item-timing |
ease |
Content transition timing |
--fs-lightbox-details-bg |
rgba(0, 0, 0, 0.6) |
Details area background |
--fs-lightbox-details-color |
#fff |
Details area text color |
--fs-lightbox-details-font |
16px / 1.4 sans-serif |
Details area font stack |
--fs-lightbox-details-padding |
... |
Details area padding |
--fs-lightbox-details-gap |
10px |
Details area spacing |
--fs-lightbox-button-background |
rgba(0, 0, 0, 0.8) |
Control button background |
--fs-lightbox-button-color |
#fff |
Control button icon color |
Classes allow deeper customization and indicate the current state of a specific instance.
| Classname | Type | Description |
|---|---|---|
.fs-lightbox |
element |
Dialog element |
.fs-lightbox-container |
element |
Content container element |
.fs-lightbox-item |
element |
Gallery item element |
.fs-lightbox-active |
modifier |
Indicates active state |
.fs-lightbox-open |
modifier |
Indicates open state |