Lightbox

Many web sites have image galleries with fantastic high-resolution images. But they present a conundrum: we want to show these images at the biggest size possible so the reader can see all of their detail, but we can’t make them all huge all the time or scrolling becomes tiresome.

Our <hotfx-lightbox> element solves this problem by letting the reader look at images in a carousel that temporarily covers the entire browser window. This is not a new solution (see prior art), but our custom element is a very straightforward and modern solution to this common interface pattern.

Here’s a simple demo that shows our lightbox in action.

To get this working, just add this script to your page:

Then add the hotfx-lightbox-slide attribute to any images that you want to show in your gallery. Something like the following:

<img src="foo.jpg" hotfx-lightbox-slide>

The script is designed to require no configuration by default, so that’s all you need to do. The script will automatically open the gallery when you click any of the images with the given attribute.

Changing Styles

The design of the lightbox is intentionally generic and compatible with many sites out of the box. However, you may wish to customize the look and feel to match your own design more closely. The lightbox is implemented as a custom HTML element, so you can alter it using part() pseudo elements:

• ::part(slide) is the image itself. Use max-height and max-width to create space around the image.
• ::part(next) and ::part(previous) are the buttons to either side of the image. You can change their size with the CSS font-size and their color using the CSS color property.
• ::part(close) is the button for closing the menu and it can be modified the same as the next and previous buttons.
• ::part(backdrop) is the gray background, which might look better if it wasn’t so gray.

In the following example, we’ve done all that for you so you can get an idea of what is possible.

Further Customization

We can get an even better level of customization by swapping out the icons. To do this, you’ll need to add the <hotfx-lightbox> custom element to your page explicitly. Normally this is done for you whenever someone clicks an image with the hotfx-lightbox-slide attribute on it.

The component provides three slots for you to fill — previous, next and close— corresponding to the three buttons on the tool. Here we swap out the close button for text and add some swank retro arrows.

Using a Selector To Add Images

Sometimes, adding the hotfx-lightbox-slide attribute to all of your images can be a pain, especially as you update your page and add or remove images. If you want to make your job a little easier, you can manually add the <hotfx-lightbox> custom element to the page and set a selector attribute on it. The following will select all image tags inside an element with the ID of “gallery.”

<hotfx-lightbox selector="#gallery img"></hotfx-lightbox>

This attribute also lets you create two different lightboxes for two different sets of images. Below we’ve added a separate lightbox for the Monet’s haystacks.

Including Captions

You can include captions. Really, any element on the page can be included in the lightbox if you add the hotfx-lightbox-slide attribute (or change the selector on the custom element, as discussed above). The somewhat tricky part, as we shall see, is styling the content in the lightbox.

The HotFX lightbox is a custom HTML element built using shadow DOM, but instead of using <slot> elements, which can be styled in light DOM, we are copying the elements from the page into the lightbox. This approach means you don’t have to duplicate your images in markup inside the <hotfx-lightbox> DOM. Including the same images again and keeping them in the correct order could be a real pain and we wanted to have a zero-config default for our component.

To style elements copied into the shadow DOM, use the part attribute on them and then the ::part() pseudo element that’s styleable from outside the shadow DOM.

So in demo the below we’ve created our images with something like this:

<figure hotfx-lightbox-slide>
  <img src="..." part="image">
  <figcaption part="caption">
    Cab Calloway, New York, N.Y., ca. Jan. 1947
  </figcaption>
</figure>

We have added part=image to the img tag and part=caption to the figcaption tag. This let’s us style the copied markup inside the lightbox using the hotfx-lightbox::part(image) and hotfx-lightbox::part(caption) selectors. This approach might be stretching the design of custom elements pretty far, but it works just fine.

Prior Art

The original lightbox script, created by Lokesh Dhakar, dates back to 2005. Those were the dark days before jQuery was even released, and of course, version 2 was later updated to use jQuery.

The original library was very successful, but the idea behind it grew even more widely. These full-window image carousels quickly became an almost must-have feature for web sites with lots of images. The same interface pattern has since become ubiquitous for mobile apps as well.

The HotFX lightbox uses some features that have only recently been widely supported by most browsers: the HTML <dialog> element, shadow DOM and CSS scroll snaps. This modern approach gives our version great support on touch devices and trackpads while using much less code than earlier libraries.

To learn more about how the element was made, check out the annotated source code. If you would like to request a feature or report a bug, please do so on the HotFX GitHub repo.