dragon-lightbox
Advanced tools
A lightweight, responsive and accessible lightbox library made in typescript
A lightweight, responsive and accessible lightbox library made in typescript
https://cmgdragon.github.io/dragon-lightbox/
Add the following script
<script src="https://cdn.jsdelivr.net/npm/dragon-lightbox@1.2.6/dist/dragon-lightbox.js"></script>
at the end of the <body> tag of your html file.
Or you can download the bundle file located in the dist folder of this repository and include it in your project!
<script src="dragon-lightbox.js"></script>
Execute npm install dragon-lightbox
and then include the javascript:
require('dragon-lightbox')
Or, if using ES6 modules:
import 'dragon-lightbox'
For getting started, add the data-dlightbox attribute to any resource you want to convert into a lightbox
<img data-dlightbox src="image.jpg" />
The plugin will automatically deduct what type of resource you are targeting based on the html tag or the resource extension.
You can also specify the resource passing it as a value in the data-dlightbox attribute
<any-tag data-dlightbox="resource.mp4"></any-tag>
For embedding videos from hird-party platforms, just use the entire url to that video.
Supported platforms are Youtube, Dailymotion and Vimeo.
The url also supports the "start time" parameter. Each provider implements it differently.
Some examples right below
Youtube: https://www.youtube.com/watch?v=XxXxXXX &t=100 Dailymotion: https://www.dailymotion.com/video/xxXXxXX ?start=20 Vimeo: https://vimeo.com/00000000 #t=30
You can create a lightbox container adding the data-dlightbox-container attribute to an element containig a list of resources
<div data-dlightbox-container>
<a href="image.jpg">Image1</a>
<img src="image.jpg">
<a data-dlightbox="https://www.youtube.com/watch?v=rHLwG3ioD4Y">Video</a>
<img src="image.png">
</div>
During the instance creation, each resource automatically receives a data-id attribute with an integer value. You can also preset this attribute that is used for opening the lightbox programatically and bind new html elements.
This plugin allows to modify the configuration for lightbox resources:
| Option | Default | Description |
|---|---|---|
lazy | true | if true, the resources only download when the user access it. Otherwise, the resource download automatically on page load |
fireevent | "click" | it allows to define the event that will open the lightbox |
autoplay | false | if true, videos and iframe videos will play automatically |
autoscale | true | if true, the resources will fill all the available space on the screen. If you specify a number, the resources will mantain a maximum width of that number in pixels. If false, the resources will keep their original size |
type | undefined | You can explicitly define the type of elements of the lightbox. TYPES: image, video, embed (the "video" only refers to resources containing video extensions like .mp4. Youtube videos are of type "embed") |
attributes | undefined | you can pass HTML attributes to the lightbox that will be applied to all its resources |
Define the configurations with the prefix data-{config}.
<div data-dlightbox-container data-autoscale="350" data-lazy="false">
<a data-autoscale data-lazy href="image1.jpg">Image1</a>
<img src="image2.jpg" alt="description" aria-label="Image 2">
<a href="image3.jpg" data-alt="description">Image1</a>
</div>
| Considerations |
|---|
| The configurations set in the container will apply for all its resources, but you can override each of them (as we do with the Image1) |
For the attributes, the plugin will take any HTML attribute for all resources and copy them to the corresponding lightbox resource. It will also copy all data-{attribute} without the data-, so if you want to add, for instance, an "alt" attribute to an anchor element, use data-alt. If you want to add an "alt" to an image, simply keep its conventional alt |
A dragonLightBox object is exposed to the window object, with a mehotd and a property:
| Method | Description |
|---|---|
create | allows the creation of lightbox objects programmatically |
| Property | Description |
|---|---|
instances | returns a map with the active lightbox instances |
To create a new lightbox programatically, use dragonLightBox.create.
Use dragonLightBox.create( resourceUrl ) , where resourceUrl is the url of the resource you want to show in a lightbox.
const instance = dragonLightBox.create('path/to/your/resource.jpg')
This will return an instance object.
You can also pass configuration as a second param:
const instance = dragonLightBox.create('path/to/your/resource.jpg', { lazy: false })
If you want to create a lightbox container, use an array of resources, where each resource is also an array:
const resources = [ ['path/to/your/resource1.jpg'], ['path/to/your/resource2.mp4'] ]
const instance = dragonLightBox.create(resources, { autoplay: true })
Now, if you want to add attributes to the resources, you must use an array of [ recource, attributes ], where the attributes is an array of objects { name, value }
| Attribute | Description |
|---|---|
name | the name of the attribute (e. g.: "aria-hidden") |
value | the value for the attribute |
const attributes = [{ name: 'aria-hidden', value: true }, { name: 'any-other-attr', value: 'any' }]
const resources = [ ['path/to/your/resource1.jpg', attributes] ] //one or more
const instance = dragonLightBox.create(resources, { autoscale: false })
You can get the instance by saving it in a variable when created with the dragonLightBox.create or accessing it with the dragonLightBox.instances.get( id )
The instance provides the following methods and properties:
| Method | Description |
|---|---|
open( number? ) | open the lightbox by its data-id. If no id provided, open the first one |
close() | close the lightbox |
listen( listener , cb ) | add a custom event listener and executes the callback provided (more info) |
bind( elements ) | bind html elements to the instance (more info) |
remove() | remove the instance and all its bindings. It does not remove the html elements |
| Property | Description |
|---|---|
elements | provides a list with the elements that the plugin will follow for generating the lightbox. If the instance has been created with the dragonLightBox.create, those elements will need to be binded if you want yo access them through the HTML |
bindings | provides a list with all the instance bindings |
These are a set of custom events that will fire when certain actions are performed in the lightbox:
| Event | Description |
|---|---|
dlightbox:open | fires when the lightbox has been opened |
dlightbox:close | fires when the lightbox has been closed |
dlightbox:change | fires when the lightbox switch to the next or previous resource (only for containers) |
The lightbox events provides a set of data that you can retrieve from the event.detail object:
| Detail | Description |
|---|---|
config | the lightbox configuration |
count | the number of resources of the lightbox |
id | id of the instance |
elements | elements that the lightbox will follow for generating itself |
selectedBox() | a function that returns an object with information with the current lightbox resource element. It provides its attributes, the resourceUrl, the element and its own config |
const instance = dragonLightBox.instances.get(0);
instance.listen('dlightbox:open', ({detail}) => console.log(detail));
To bind a lightbox resource means that you are linking the resource with an HTML element that will open that resource with a DOM event.
When you are creating lightboxes declarativelly with the data-dlightbox attribute, those elements are being binded to the lightbox automatically.
If you need more, you can bind new HTML elements to the lightbox instances, and assign a custom event that will open the lightbox.
For it, use the bind( elements )
As a only parameter, you can pass a querySelector of the elements to be binded.
const instance = dragonLightBox.instances.get(0);
instance.bind( document.querySelector('#toBind') )
| Considerations |
|---|
By default, a click event is registered. |
When a click event is registered, automatically adds a keydown (Enter) event to the same HTML elements |
| The number of elements to bind must be equal to the number of resources in the lightbox! |
Optionally, you can specify the event to listen. In that case you need to provide an object { elements, fireevent } to the bind() method:
const instance = dragonLightBox.instances.get(0);
const instanceEvents = { elements: document.querySelector('#toBind'), fireevent: 'dblclick' }
instance.bind( instanceEvents )
data-id for bindingThe binding process will match those elements that have the same data-id with the data-id of the resources. If no matching data-id is provided to the HTML element, it will bind the elements in list order.
//this lightbox resources with `data-id` "1" and "2"...
const resources = [
['resource1.jpg', { name: 'data-id', value: 1 }],
['resource2.jpg', { name: 'data-id', value: 2 }]
]
const instance = dragonLightBox.create(resources);
instance.bind( document.querySelectorAll('#binding > div') )
<!-- ...will bind the `data-id` of the following elements -->
<div id="binding">
<div data-id="2">Bind2</div>
<div data-id="1">Bind1</div>
</div>
If you are interested of extending the project, clone it and execute
npm run devThis will start the development environment, that uses the index.html file located in the root folder
For building the plugin for production, just hit
npm run buildThis will create an optimized file inside the dist folder
Finally, do not hesitate to fork / report issues if you want to contribute!
FAQs
A lightweight, responsive and accessible lightbox library made in typescript
We found that dragon-lightbox demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."