Lightbox
Bootstrap 5 Lightbox component
Responsive lightbox built with the latest Bootstrap 5. Lightbox is a responsive gallery with the option to enlarge selected photos.
MDB lightbox is a group of images combined in one responsive gallery. Elements are grouped in a thumbnail grid, which can be displayed as a slideshow.
Note: Read the API tab to find all available options and advanced customization
Required ES init:
Lightbox
*
* UMD autoinits are enabled
by default. This means that you don't need to initialize
the component manually. However if you are using MDBootstrap ES format then you should pass
the required components to the initMDB method.
Basic example
A basic example of a lightbox with the most common use case with the bootstrap grid.
<div class="lightbox" data-mdb-lightbox-init>
<div class="row">
<div class="col-lg-4">
<img
src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Slides/1.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Slides/1.webp"
alt="Table Full of Spices"
class="w-100"
/>
</div>
<div class="col-lg-4">
<img
src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Slides/2.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Slides/2.webp"
alt="Winter Landscape"
class="w-100"
/>
</div>
<div class="col-lg-4">
<img
src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Slides/3.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Slides/3.webp"
alt="View of the City in the Mountains"
class="w-100"
/>
</div>
</div>
</div>
// Initialization for ES Users
import { Lightbox, initMDB } from "mdb-ui-kit";
initMDB({ Lightbox });
Image optimization
To ensure the proper performance of the page, it is recommended to include thumbnails of
images in the src attribute. Then in the
data-mdb-img attribute add the path to the image with higher resolution. If the
data-mdb-img attribute is omitted, the lightbox will display the same image as in
the reduced size.
<img
src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Slides/1.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Slides/1.webp"
alt="Table Full of Spices"
class="w-100"
/>
Shadows and rounded corners
You can improve the look of the images by adding shadows and rounded corners.
<div class="lightbox" data-mdb-lightbox-init>
<div class="row">
<div class="col-lg-4">
<img
src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Slides/1.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Slides/1.webp"
alt="Table Full of Spices"
class="w-100 shadow-1-strong rounded"
/>
</div>
<div class="col-lg-4">
<img
src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Slides/2.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Slides/2.webp"
alt="Winter Landscape"
class="w-100 shadow-1-strong rounded"
/>
</div>
<div class="col-lg-4">
<img
src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Slides/3.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Slides/3.webp"
alt="View of the City in the Mountains"
class="w-100 shadow-1-strong rounded"
/>
</div>
</div>
</div>
// Initialization for ES Users
import { Lightbox, initMDB } from "mdb-ui-kit";
initMDB({ Lightbox });
Different sizes
Loaded images can have any aspect ratio. Their size will be automatically adjusted to the window when you open the lightbox.
<div class="lightbox" data-mdb-lightbox-init>
<div class="row">
<div class="col-lg-6">
<img
src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Slides/1.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Slides/1.webp"
alt="Table Full of Spices"
class="w-100 mb-2 mb-md-4"
/>
<img
src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Square/1.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Square/1.webp"
alt="Coconut with Strawberries"
class="w-100"
/>
</div>
<div class="col-lg-6">
<img
src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Vertical/1.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Vertical/1.webp"
alt="Dark Roast Iced Coffee"
class="w-100"
/>
</div>
</div>
</div>
// Initialization for ES Users
import { Lightbox, initMDB } from "mdb-ui-kit";
initMDB({ Lightbox });
Zoom level
The data-mdb-zoom-level attribute allows you to define the size of a single zoom
in / zoom out.
<div class="lightbox" data-mdb-zoom-level="0.25" data-mdb-lightbox-init>
<div class="row">
<div class="col-lg-4">
<img
src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Slides/1.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Slides/1.webp"
alt="Table Full of Spices"
class="w-100"
/>
</div>
<div class="col-lg-4">
<img
src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Slides/2.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Slides/2.webp"
alt="Winter Landscape"
class="w-100"
/>
</div>
<div class="col-lg-4">
<img
src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Slides/3.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Slides/3.webp"
alt="View of the City in the Mountains"
class="w-100"
/>
</div>
</div>
</div>
// Initialization for ES Users
import { Lightbox, initMDB } from "mdb-ui-kit";
initMDB({ Lightbox });
Disabled image
By adding a lightbox-disabled class to any image, you can exclude it from your
lightbox. In the example below, the third image has been disabled.
<div class="lightbox" data-mdb-lightbox-init>
<div class="row">
<div class="col-lg-3">
<img
src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Slides/1.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Slides/1.webp"
alt="Table Full of Spices"
class="w-100"
/>
</div>
<div class="col-lg-3">
<img
src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Slides/2.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Slides/2.webp"
alt="Winter Landscape"
class="w-100"
/>
</div>
<div class="col-lg-3">
<img
src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Slides/3.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Slides/3.webp"
alt="Disabled image"
class="w-100 lightbox-disabled"
/>
</div>
<div class="col-lg-3">
<img
src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Slides/4.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Slides/4.webp"
alt="Place Royale Bruxelles"
class="w-100"
/>
</div>
</div>
</div>
// Initialization for ES Users
import { Lightbox, initMDB } from "mdb-ui-kit";
initMDB({ Lightbox });
Captions
Image captions can be added using the data-mdb-caption attribute. If it is not
set, the data is taken from the alt attribute. When you want to disable caption,
leave the data-mdb-caption empty.
<div class="lightbox" data-mdb-lightbox-init>
<div class="row">
<div class="col-lg-4">
<img data-mdb-caption="Image caption 1" src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Slides/1.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Slides/1.webp" alt="Table Full of Spices"
class="w-100" />
</div>
<div class="col-lg-4">
<img data-mdb-caption="Image caption 2" src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Slides/2.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Slides/2.webp" alt="Winter Landscape" class="w-100" />
</div>
<div class="col-lg-4">
<img data-mdb-caption="Image caption 3" src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Slides/3.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Slides/3.webp" alt="View of the City in the Mountains"
class="w-100" />
</div>
</div>
</div>
// Initialization for ES Users
import { Lightbox, initMDB } from "mdb-ui-kit";
initMDB({ Lightbox });
Outside access
The lightbox can be successfully operated via JavaScript. There are many public methods
available such as open, slide, zoomIn,
zoomOut, or close. All are described in the API tab.
<div class="lightbox" id="lightbox" data-mdb-lightbox-init>
<div class="row">
<div class="col-lg-4">
<img
src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Slides/1.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Slides/1.webp"
alt="Table Full of Spices"
class="w-100"
/>
</div>
<div class="col-lg-4">
<img
src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Slides/2.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Slides/2.webp"
alt="Winter Landscape"
class="w-100"
/>
</div>
<div class="col-lg-4">
<img
src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Slides/3.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Slides/3.webp"
alt="View of the City in the Mountains"
class="w-100"
/>
</div>
</div>
</div>
<div class="text-center mt-3">
<button class="btn btn-primary" id="lightboxToggler">
Open second image
</button>
</div>
// Initialization for ES Users
import { Lightbox, initMDB } from "mdb-ui-kit";
initMDB({ Lightbox });
const lightbox = document.getElementById('lightbox');
const lightboxInstance = Lightbox.getInstance(lightbox);
const lightboxToggler = document.getElementById('lightboxToggler');
lightboxToggler.addEventListener('click', () => {
lightboxInstance.open(1);
});
const lightbox = document.getElementById('lightbox');
const lightboxInstance = mdb.Lightbox.getInstance(lightbox);
const lightboxToggler = document.getElementById('lightboxToggler');
lightboxToggler.addEventListener('click', () => {
lightboxInstance.open(1);
});
Lightbox - API
Import
Importing components depends on how your application works. If you intend to use the MDBootstrap ES format, you must
first import the component and then initialize it with the initMDB method. If you are going to use the UMD format,
just import the mdb-ui-kit package.
import { Lightbox, initMDB } from "mdb-ui-kit";
initMDB({ Lightbox });
import "mdb-ui-kit"
Usage
Via data attributes
Using the Lightbox component doesn't require any additional JavaScript code - simply add
data-mdb-lightbox-init attribute to
.lightbox
and use other data attributes to set all options.
For ES format, you must first import and call the initMDB method.
<div class="lightbox" data-mdb-zoom-level="0.5">
<img
src="https://mdbcdn.b-cdn.net/img/Photos/Thumbnails/Slides/1.webp"
data-mdb-img="https://mdbcdn.b-cdn.net/img/Photos/Slides/1.webp"
alt="Lightbox image 1"
class="w-100"
/>
</div>
Via JavaScript
const lightbox = document.getElementById('lightbox');
const instance = mdb.Lightbox.getInstance(lightbox);
instance.open();
Via jQuery
Note: By default, MDB does not include jQuery and you have to add it to the project on your own.
$(document).ready(() => {
$('#lightbox').lightbox('open');
});
Options
Options can be passed via data attributes or JavaScript. For data attributes, append the option name to
data-mdb-, as in data-mdb-zoom-level="1".
The img and caption attributes should be pinned directly to the
thumbnails, not to the lightbox wrapper element.
| Name | Type | Default | Description |
|---|---|---|---|
container |
String | 'body' |
Allows to set the parent element for the lightbox. |
zoomLevel
|
Number / String | 1 |
Defines zoom level while zooming in or out. |
img |
String | |
Defines regular image to load when gallery is open. If not set, the value of
src attribute is taken.
|
caption
|
String | |
Defines caption of the image. If not set, the value of
alt attribute is taken.
|
Methods
| Name | Description | Example |
|---|---|---|
open |
Opens the gallery and activates image set by the target key. Default is the first image. | myLightbox.open(1) |
slide |
Slides an image in the gallery. Available options: left,
right, first, last. Dafault is right direction.
|
myLightbox.slide('last')
|
zoomIn |
Zooms in active image by one level. |
myLightbox.zoomIn()
|
zoomOut
|
Zooms out active image by one level. |
myLightbox.zoomOut()
|
toggleFullscreen
|
Toggles fullscreen. |
myLightbox.toggleFullscreen()
|
reset |
Resets changed parameters such as position, zoom or fullscreen. | myLightbox.reset() |
close |
Closes the gallery. | myLightbox.close() |
dispose
|
Removes the Lightbox instance. |
myLightbox.dispose()
|
getInstance
|
Static method which allows to get the lightbox instance associated with a DOM element. |
Lightbox.getInstance(element)
|
getOrCreateInstance
|
Static method which returns the lightbox instance associated to a DOM element or create a new one in case it wasn't initialized. |
Lightbox.getOrCreateInstance(element)
|
const lightbox = document.getElementById('lightbox');
const instance = Lightbox.getInstance(lightbox);
instance.open(1);
const lightbox = document.getElementById('lightbox');
const instance = mdb.Lightbox.getInstance(lightbox);
instance.open(1);
Events
| Name | Description |
|---|---|
open.mdb.lightbox
|
Emitted when a lightbox has been toggled. |
opened.mdb.lightbox
|
Emitted when a lightbox is opened. |
slide.mdb.lightbox
|
Emitted when a lightbox has been slid. |
slid.mdb.lightbox
|
Emitted after the lightbox has completed its slide transition. |
zoomIn.mdb.lightbox
|
Emitted when an image zooms in. |
zoomedIn.mdb.lightbox
|
Emitted after zoom in animation is over. |
zoomOut.mdb.lightbox
|
Emitted when an image zooms out. |
zoomedOut.mdb.lightbox
|
Emitted after zoom out animation is over. |
close.mdb.lightbox
|
Emitted when the lightbox closes. |
closed.mdb.lightbox
|
Emitted when the lightbox closing animation is over |
window.addEventListener('opened.mdb.lightbox', () => {
alert('Lightbox opened')
});
CSS variables
As part of MDB’s evolving CSS variables approach, lightbox now uses local CSS variables on
.lightbox-gallery for enhanced real-time customization. Values for the CSS variables are
set via Sass, so Sass customization is still supported, too.
// .lightbox-gallery
--#{$prefix}lightbox-zindex: #{$lightbox-zindex};
--#{$prefix}lightbox-toolbar-zindex: #{$lightbox-toolbar-zindex};
--#{$prefix}lightbox-gallery-background-color: #{$lightbox-gallery-background-color};
--#{$prefix}lightbox-gallery-transition: #{$lightbox-gallery-transition};
--#{$prefix}lightbox-gallery-toolbar-height: #{$lightbox-gallery-toolbar-height};
--#{$prefix}lightbox-gallery-toolbar-transition: #{$lightbox-gallery-toolbar-transition};
--#{$prefix}lightbox-gallery-toolbar-button-width: #{$lightbox-gallery-toolbar-button-width};
--#{$prefix}lightbox-gallery-toolbar-button-height: #{$lightbox-gallery-toolbar-button-height};
--#{$prefix}lightbox-gallery-toolbar-button-color: #{$lightbox-gallery-toolbar-button-color};
--#{$prefix}lightbox-gallery-toolbar-button-transition: #{$lightbox-gallery-toolbar-button-transition};
--#{$prefix}lightbox-gallery-toolbar-button-hover-color: #{$lightbox-gallery-toolbar-button-hover-color};
--#{$prefix}lightbox-gallery-content-top: #{$lightbox-gallery-content-top};
--#{$prefix}lightbox-gallery-content-left: #{$lightbox-gallery-content-left};
--#{$prefix}lightbox-gallery-content-width: #{$lightbox-gallery-content-width};
--#{$prefix}lightbox-gallery-content-height: #{$lightbox-gallery-content-height};
--#{$prefix}lightbox-gallery-arrow-width: #{$lightbox-gallery-arrow-width};
--#{$prefix}lightbox-gallery-arrow-transition: #{$lightbox-gallery-arrow-transition};
--#{$prefix}lightbox-gallery-arrow-button-width: #{$lightbox-gallery-arrow-button-width};
--#{$prefix}lightbox-gallery-arrow-button-height: #{$lightbox-gallery-arrow-button-height};
--#{$prefix}lightbox-gallery-arrow-button-color: #{$lightbox-gallery-arrow-button-color};
--#{$prefix}lightbox-gallery-arrow-button-transition: #{$lightbox-gallery-arrow-button-transition};
--#{$prefix}lightbox-gallery-arrow-button-hover-color: #{$lightbox-gallery-arrow-button-hover-color};
--#{$prefix}lightbox-gallery-button-focus-color: #{$lightbox-gallery-button-focus-color};
--#{$prefix}lightbox-gallery-image-transform: #{$lightbox-gallery-image-transform};
--#{$prefix}lightbox-gallery-image-transition: #{$lightbox-gallery-image-transition};
--#{$prefix}lightbox-gallery-counter-color: #{$lightbox-gallery-counter-color};
--#{$prefix}lightbox-gallery-counter-padding-x: #{$lightbox-gallery-counter-padding-x};
--#{$prefix}lightbox-gallery-caption-color: #{$lightbox-gallery-caption-color};
--#{$prefix}lightbox-gallery-caption-margin-x: #{$lightbox-gallery-caption-margin-x};
--#{$prefix}lightbox-gallery-caption-wrapper-height: #{$lightbox-gallery-caption-wrapper-height};
--#{$prefix}lightbox-gallery-loader-transition: #{$lightbox-gallery-loader-transition};
--#{$prefix}lightbox-icons-font: var(--fa-font-solid);
// .disabled-scroll
--#{$prefix}lightbox-disabled-scroll-media-padding-right: #{$lightbox-disabled-scroll-media-padding-right};
SCSS variables
$lightbox-zindex: 1100;
$lightbox-zindex-toolbar: 1110;
$lightbox-gallery-background-color: rgba(0, 0, 0, 0.9);
$lightbox-gallery-transition: all 0.3s ease-out;
$lightbox-gallery-toolbar-height: 50px;
$lightbox-gallery-toolbar-transition: opacity 0.4s;
$lightbox-gallery-counter-color: #b3b3b3;
$lightbox-gallery-counter-padding-x: 10px;
$lightbox-gallery-toolbar-button-width: 50px;
$lightbox-gallery-toolbar-button-height: 50px;
$lightbox-gallery-toolbar-button-color: #b3b3b3;
$lightbox-gallery-toolbar-button-transition: color 0.2s;
$lightbox-gallery-toolbar-button-hover-color: $white;
$lightbox-gallery-toolbar-button-before-font-weight: 900;
$lightbox-gallery-content-top: 50px;
$lightbox-gallery-content-left: $lightbox-gallery-content-top;
$lightbox-gallery-content-width: calc(100% - 100px);
$lightbox-gallery-content-height: $lightbox-gallery-content-width;
$lightbox-gallery-image-transform: scale(0.25);
$lightbox-gallery-image-transition: all 0.4s ease-out;
$lightbox-gallery-arrow-width: 50px;
$lightbox-gallery-arrow-transition: opacity 0.4s;
$lightbox-gallery-arrow-button-width: 50px;
$lightbox-gallery-arrow-button-height: 50px;
$lightbox-gallery-arrow-button-color: #b3b3b3;
$lightbox-gallery-arrow-button-transition: color 0.2s;
$lightbox-gallery-arrow-button-hover-color: $white;
$lightbox-gallery-arrow-button-before-font-weight: 900;
$lightbox-gallery-caption-wrapper-height: 50px;
$lightbox-gallery-caption-color: $white;
$lightbox-gallery-caption-margin-x: 10px;
$lightbox-gallery-loader-transition: opacity 1s;
$lightbox-gallery-button-focus-color: $white;
$lightbox-disabled-scroll-media-padding-right: 17px;