DBox - An Image Lightbox using HTML5 Dialog Element

Monday August 7, 2017

This post is over six (6) months old. Some things on this page my be out of date or no longer applicable.

Dbox is an image lightbox written in es6 with no external dependencies — that is not dependent on JQuery.

File Sizes
File	Size in KB	Gzip Size in KB
dbox.min.css	≈3.0KB	≈1.7KB
dbox.min.js	≈17.3KB	≈6.4KB
dbox.noPollyFill.min.js	≈7.9KB	≈3.5KB
dbox.noColorThief.min.js	≈11.5KB	≈4.3KB

Quick Start

Download the latest release from github and insert the provided CSS into the head of your document and the provided JavaScript file before your closing </head> tag.

<head>
    <!-- your other files and markup on your head -->
    <!-- The dbox css -->
    <link rel="stylesheet" href="dist/css/dbox.min.css">

    <!-- The dbox JS file -->
    <script src="dist/js/dbox.min.js" defer></script>
</head>

Markup an image to be placed in a lightbox. Include a thumbnail image and the larger image you wish to show in the lightbox. The Anchor tag (<a>) needs to have a class of dbox.

<!-- a responsive image example -->
    <a class="dbox" href="your/lightboxed/image.jpg">
      <img sizes="(min-width: 530px) 25vw, 100vw"
           srcset="your/thumb/image-177w.png 177w,
              your/thumb/image-240w.png 240w,
              your/thumb/image-321w.png 321w,
              img/thumb/640-th.png 367w"
           src="img/thumb/640-th.png"
           alt="Your Alt Text Used For the Lightbox Caption"
           class=""
           width="100%"
      >
    </a>

    <!-- a regular image example -->
    <a class="dbox" href="your/lightboxed/image.jpg">
       <img sizes="25vw" src="your/thumb/image-th.jpg"
            alt="Your Alt Text Used For the Lightbox Caption"
            class="any classes used to style your image"
            width="100%"
       >
     </a>

Before your closing body tag, insert the dialog element and initialize the dbox script.

<dialog id="js-dbox" class="dbox-dialog">
  <div class="dbox-dialog--content">
    <img src="" alt="" class="dbox-dialog--image">
    <div class="dbox-dialog--container">
      <p class="dbox-dialog--caption"></p>
      <button type="button" class="dbox-dialog--close">close</button>
    </div>
  </div>
</dialog>

<script>
    document.addEventListener("DOMContentLoaded", function () {
    // you could also use var instead of let here
      let lightbox = new Dbox();
      lightbox.run();
    });
</script>

The default anchor class is dbox if you'd wish to change this to something else you need to pass it to the constructor at the end of your page or in your own JS file. The new class will be used for the 'element' key. Classes must be prefixed with a period and ID's with a hash mark.

<a class="myNewClass" href="your/lightboxed/image.jpg">
    <img sizes="25vw" src="your/thumb/image-th.jpg"
        alt="Your Alt Text Used For the Lightbox Caption"
        class="any classes used to style your image"
        width="100%"
    >
</a>

document.addEventListener("DOMContentLoaded", function () {
    // you could also use var instead of let here
      let lightbox = new Dbox( {
          element: '.myNewClass'
          // or using an id
          element: '#myNewID'
        } );
      lightbox.run();
    });

Changing The Dialog ID

The default ID that dbox looks for to open your lightbox is js-dbox. If you have multiple dialog types in a page you'll need a dialog element for each one with a unique ID. Pass this new id with hash mark included to the dialogBox key.

<dialog id="myNewDialogID" class="dbox-dialog">
    <div class="dbox-dialog--content">
        <img src="" alt="" class="dbox-dialog--image">
        <div class="dbox-dialog--container">
          <p class="dbox-dialog--caption"></p>
            <button type="button" class="dbox-dialog--close">close</button>
        </div>
    </div>
</dialog>

document.addEventListener("DOMContentLoaded", function () {
    // you could also use var instead of let here
      let lightbox = new Dbox( {
          dialogBox: '.myNewDialogClass'
          // or using an id
          element: '#myNewDialogID'
        } );
      lightbox.run();
    });

Using Dbox as a Modal

Dbox has two modes to operate in. One is a normal dialog / lightbox mode. Clicking anywhere on the image or backdrop will close the lightbox. The second mode is a modal mode. The lightbox will only close when the 'close' button is clicked. You have hto pass 'modal: true' to the constructor.

document.addEventListener("DOMContentLoaded", function () {
    // you could also use var instead of let here
      let lightbox = new Dbox( {
          modal: true
        } );
      lightbox.run();
    });

Modal Example. Click the image to open a modal lightbox

Using Dbox without a PolyFill or ColorThief

If you want to live on the edge and only support one browser — you shouldn't do this but I'll let you :) — you can use the dbox.noPolyfill.min.js file found in dist/js directory.

If you have a server side solution for getting an images dominant color you can use the file dbox.noColorThief.min.js found in the dist/js directory.

Dbox Limitations

Dbox uses object-fit: to display images in the lightbox. This is only supported in

Firefox 36+
- FireFox for Android
Chrome 31+
- Chrome For Android
Safari 7.1+
- iOS Safari 8+
Opera 19+
- Opera Mobile 12+
Opera Mini
Android Browser 4.4.4+
Samsung Internet 4+

So images will be "stretched" on large screens that don't support object-fit. The images below show the difference between Firefox that supports object-fit and Edge 15 which doesn't.

FireFox

Milky Way Above Bend in Forested Shoreline By Eric Kilby

Edge 15 No Object Fit

The object-fit polyfills I found didn't work very well so I opted to not use them. If you wish to try you can find one at object-fit-images . It also links to other available polyfills. You'll use this at your own discretion. I don't plan on debugging any object-fit polyfill usage with this library.

Dbox also uses Color Thief to get the dominant color of an image. If your thumbnail image is large then this could cause a delay since it has to process a large image.

Browser Support

As shown above this supports all "modern" browsers. So Edge, Firefox, Chrome, Opera, Safari.

Internet Explorer 11 is "supported" but you'll have to include some of your own custom CSS to properly align the dialog box in the window when it's opened.

Internet Explorer 11 misaligned dialog backdrop

Why Dbox?

Why did I build Dbox? HTML5.1 initially introduced the dialog element . It makes using and making dialogs, modals and lightboxes super easy. The current browser support (as of this posting) isn't very good but there is a small polyfill included in this library to over come that.

Can I Use dialog? Data on support for the dialog feature across the major browsers from caniuse.com.

In one of Twitter's recent updates they started to apply a dominant color to the image's description on desktop and the background on mobile

Twitter Lightbox on a Desktop

Twitter Lightbox on a phone

I really liked that. So I wanted to replicate it

Cory Dowdy