All-in-One Modal Lightbox Solution For Web Developers – DimBox.js

Preview:

Description:

DimBox.js is a lightweight yet powerful and customizable JavaScript popup library for creating stunning modals & lightboxes on your website.

It supports a variety of content types, including images, galleries, HTML5/YouTube/Vimeo videos, iframe content, AJAX content, inline content, and much more.

How to use it:

1. Install and import the DimBox.js library.

# NPM
$ npm i dimbox

// ES Module
import dimbox from 'dimbox';

// Browser
<link rel="stylesheet" href="dist/css/dimbox.min.css" />
<script src="dist/js/dimbox.min.js"></script>

2. Create modal popups using the following HTML data attributes:

• data-dimbox: Required. All links having the same value will be shown in a gallery lightbox.
• data-dimbox-caption: Text to be displayed at the bottom of the modal.
• data-dimbox-ratio: 16×9, 4×3, 1×1 and 9×16.
• data-dimbox-type: image, video, iframe, inline and ajax.
• data-dimbox-download-file: Defines a file to download by clicking the download button.
• data-dimbox-thumbnail: Defines the path to a custom thumbnail image.

<!-- Image Lightbox -->
<a href="1.jpg" data-dimbox="my-image" data-dimbox-caption="Image Description">
  Image
</a>
<!-- Video Lightbox -->
<a href="https://www.youtube.com/embed/j4a2uCvbfAc" data-dimbox="youtube" data-dimbox-ratio="16x9">
  YouTube Video
</a>
<a href="https://player.vimeo.com/video/43588364" data-dimbox="vimeo" data-dimbox-ratio="16x9">
  Vimeo Video
</a>
<a href="/path/to/1.mp4" data-dimbox="html5video">
  HTML5 Video
</a>
<!-- AJAX Modal -->
<a href="/path/to/endpoint/" data-dimbox="ajax" data-dimbox-type="ajax">
  Ajax Content
</a>
<!-- Iframe Modal -->
<a href="/path/to/url/" data-dimbox="iframe">
  iFrame Content
</a>
<!-- Inline Modal -->
<a href="#inlineContent" data-dimbox="inline">
  Inline Content
</a>
<div id="inlineContent" class="d-none">
  Make sure to hide the DIV on page load
</div>

3. Override the default configs.

dimbox.setConfig({
  // close the modal on click outside
  closeOnOverlayClick: true,
   // Fullscreen options
  fullscreen: false,
  showFullscreenButton: true,
  svgFullscreenButton: '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path d="M1.5 1a.5.5 0 0 0-.5.5v4a.5.5 0 0 1-1 0v-4A1.5 1.5 0 0 1 1.5 0h4a.5.5 0 0 1 0 1zM10 .5a.5.5 0 0 1 .5-.5h4A1.5 1.5 0 0 1 16 1.5v4a.5.5 0 0 1-1 0v-4a.5.5 0 0 0-.5-.5h-4a.5.5 0 0 1-.5-.5M.5 10a.5.5 0 0 1 .5.5v4a.5.5 0 0 0 .5.5h4a.5.5 0 0 1 0 1h-4A1.5 1.5 0 0 1 0 14.5v-4a.5.5 0 0 1 .5-.5m15 0a.5.5 0 0 1 .5.5v4a1.5 1.5 0 0 1-1.5 1.5h-4a.5.5 0 0 1 0-1h4a.5.5 0 0 0 .5-.5v-4a.5.5 0 0 1 .5-.5"/></svg>',
  svgFullscreenExitButton: <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path d="M5.5 0a.5.5 0 0 1 .5.5v4A1.5 1.5 0 0 1 4.5 6h-4a.5.5 0 0 1 0-1h4a.5.5 0 0 0 .5-.5v-4a.5.5 0 0 1 .5-.5m5 0a.5.5 0 0 1 .5.5v4a.5.5 0 0 0 .5.5h4a.5.5 0 0 1 0 1h-4A1.5 1.5 0 0 1 10 4.5v-4a.5.5 0 0 1 .5-.5M0 10.5a.5.5 0 0 1 .5-.5h4A1.5 1.5 0 0 1 6 11.5v4a.5.5 0 0 1-1 0v-4a.5.5 0 0 0-.5-.5h-4a.5.5 0 0 1-.5-.5m10 1a1.5 1.5 0 0 1 1.5-1.5h4a.5.5 0 0 1 0 1h-4a.5.5 0 0 0-.5.5v4a.5.5 0 0 1-1 0z"/></svg>
  // the image icon used in thumbnails for image type content if no thumbnail image could be loaded
  svgImageIcon: <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-image" viewBox="0 0 16 16"><path d="M6.002 5.5a1.5 1.5 0 1 1-3 0 1.5 1.5 0 0 1 3 0"/><path d="M2.002 1a2 2 0 0 0-2 2v10a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V3a2 2 0 0 0-2-2zm12 1a1 1 0 0 1 1 1v6.5l-3.777-1.947a.5.5 0 0 0-.577.093l-3.71 3.71-2.66-1.772a.5.5 0 0 0-.63.062L1.002 12V3a1 1 0 0 1 1-1z"/></svg>,
  // 16x9, 4x3, 1x1 and 9x16
  iframeRatio: '16x9',
  // default selector
  selector: 'a[data-dimbox]',
  // allows the user to download the media
  showDownloadButton: true,
  // custom icons
  svgCloseButton: '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path d="M2.146 2.854a.5.5 0 1 1 .708-.708L8 7.293l5.146-5.147a.5.5 0 0 1 .708.708L8.707 8l5.147 5.146a.5.5 0 0 1-.708.708L8 8.707l-5.146 5.147a.5.5 0 0 1-.708-.708L7.293 8 2.146 2.854Z"/></svg>',
  svgDownloadButton: '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path d="M.5 9.9a.5.5 0 0 1 .5.5v2.5a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-2.5a.5.5 0 0 1 1 0v2.5a2 2 0 0 1-2 2H2a2 2 0 0 1-2-2v-2.5a.5.5 0 0 1 .5-.5z"/><path d="M7.646 11.854a.5.5 0 0 0 .708 0l3-3a.5.5 0 0 0-.708-.708L8.5 10.293V1.5a.5.5 0 0 0-1 0v8.793L5.354 8.146a.5.5 0 1 0-.708.708l3 3z"/></svg>',
  svgPrevNextButton: '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M4.646 1.646a.5.5 0 0 1 .708 0l6 6a.5.5 0 0 1 0 .708l-6 6a.5.5 0 0 1-.708-.708L10.293 8 4.646 2.354a.5.5 0 0 1 0-.708z"/></svg>',
  svgVideoIcon: '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-play-fill" viewBox="0 0 16 16"><path d="m11.596 8.697-6.363 3.692c-.54.313-1.233-.066-1.233-.697V4.308c0-.63.692-1.01 1.233-.696l6.363 3.692a.802.802 0 0 1 0 1.393"/></svg>',
  // or light
  theme: 'dark',
  // When set to true gallery thumbnail images are shown below the image when DimBox is open. 
  // This requires the gallery to have more than one item. 
  // By default the image used as link will be shown as a thumbnail. 
  // If the link element doesn't contain an image a generic placeholder will be used.
  thumbnails: false,
  // video options
  videoAutoplay: true,
  videoControls: true,
  videoLoop: false,
  videoVolume: null,
  // XHR response type
  xhrResponseType: 'json',
  // custom templates
  ajaxTemplate: `
    <div class="dimbox-ajax-container">
      <div class="dimbox-ajax-content">{{content}}</div>
      <div class="dimbox-caption">{{caption}}</div>
    </div>
  `,
  imageTemplate: `
  <figure class="dimbox-figure">
    <img src="{{src}}" class="dimbox-image" alt="{{alt}}" />
    <figcaption class="dimbox-caption">{{caption}}</figcaption>
  </figure>`,
  iframeTemplate: `
  <div class="dimbox-iframe-container">
    <iframe src="{{src}}" class="dimbox-iframe"></iframe>
    <div class="dimbox-caption">{{caption}}</div>
  </div>
  `,
  inlineTemplate: `
  <div class="dimbox-inline-container">
    <div class="dimbox-inline-content">{{content}}</div>
    <div class="dimbox-caption">{{caption}}</div>
  </div>
  `,
  sequenceTemplate: '<span class="dimbox-sequence-current">{{current}}</span> / <span class="dimbox-sequence-total">{{total}}</span>',
  videoTemplate: `
  <div class="dimbox-video-container">
    <video src="{{src}}" class="dimbox-video"></video>
    <div class="dimbox-caption">{{caption}}</div>
  </div>
  `,
  // callbacks
  onBeforeOpen: function() {
    console.log('onBeforeOpen event callback here hi!');
  },
  onAfterOpen: function() {
    console.log('onAfterOpen event callback here hi!');
  },
  onBeforeUpdateContent: function() {
    console.log('onBeforeUpdateContent event callback here hi!');
  },
  onAfterUpdateContent: function() {
    console.log('onAfterUpdateContent event callback here hi!');
  },
  onContentLoaded: function() {
    console.log('onContentLoaded event callback here hi!');
  },
  onDownload: function() {
    console.log('onDownload event callback here hi!');
  },
  onBeforeEnterFullscreen: function() {
    console.log('onBeforeEnterFullscreen event callback here hi!');
  },
  onAfterEnterFullscreen: function() {
    console.log('onAfterEnterFullscreen event callback here hi!');
  },
  onBeforeExitFullscreen: function() {
    console.log('onBeforeExitFullscreen event callback here hi!');
  },
  onAfterExitFullscreen: function() {
    console.log('onAfterExitFullscreen event callback here hi!');
  },
  onBeforeClose: function() {
    console.log('onBeforeClose event callback here hi!');
  },
  onAfterClose: function() {
    console.log('onAfterClose event callback here hi!');
  }
});

4. API methods.

// close
dimbox.close();
// go to the next item
dimbox.next();
// back to the previous item
dimbox.previous();
// open an element
var myAElement = document.getElementById('myAElement');
dimbox.open(myAElement);

Changelog:

v1.2.1 (06/05/2025)

• Fixed a bug that caused data-dimbox-download-file attribute not to work in galleries except for the first opened image.

v1.2.0 (02/22/2025)

• Added an option to show thumbnails

v1.1.4 (12/14/2024)

• Passing a reference to the current a element as an argument for callback function calls onBeforeUpdateContent, onAfterUpdateContent and onContentLoaded.

v1.1.3 (11/16/2024)

• Added: Data attribute data-dimbox-download-file.
• Changed: Renamed function downloadRemoteImage to downloadRemoteFile.

v1.1.2 (09/11/2024)

• Fix closing DimBox on esc key press with single content.

v1.1.1 (09/11/2024)

• Close DimBox on esc key press.

v1.1.0 (07/06/2024)

• Added Fullscreen functionality
• Added Event hooks onAfterEnterFullscreen, onAfterExitFullscreen, onBeforeEnterFullscreen and onBeforeExitFullscreen
• Added Config options fullscreen, showFullscreenButton, svgFullscreenButton and svgFullscreenExitButton

v1.0.6 (07/01/2024)

• Added Error message on XHR error when loading ajax content.

v1.0.5 (06/30/2024)

• Support for downloading files from a different domain (Access-Control-Allow-Origin header needs to be set on the remote server).

v1.0.4 (06/23/2024)

• Added new option: preventScroll

v1.0.3 (09/11/2023)

• Add focus trapping when DimBox is open.