SuperModal.js

SuperModal.js an image modal that gets out of the way

Galleries, zoom, swipe, a slideshow and a grid view for the images on your page. No dependencies, 9.5 KB of JavaScript gzipped.

Get v1.0.0
Green and red polar lights Neon light trails in Munich Orange reflective architecture Spiral staircase Desktop purple neon light
Lights on the roof Twisting building facade Coding workstation Swiss Cheese Architecture Water, Light and long shutter speeds

Click any frame. On a phone, swipe the strips sideways.

What it does

You write plain links to your images. SuperModal turns them into a full-screen viewer that works the same with a mouse, a keyboard or a finger.

Try it

Each demo shows the markup or the call that produced it. The event log under the JavaScript demo records every demo on this page.

A gallery in the light theme

Options can travel with the markup: the first link's JSON sets the light theme for the whole gallery. Press G for the grid view.

Boat Ship Boats Ships Cargo Harbor Bridge River Fishingboat Ship Sunset Sea Catalina Harbor
<a href="images/harbour/world-04.webp"
   data-supermodal='{"group":"harbour","theme":"light","title":"Boat Ship"}'>
  <img src="images/harbour/world-04-480.webp" alt="Boat Ship">
</a>
<a href="images/harbour/world-09.webp"
   data-supermodal='{"group":"harbour","title":"Boats Ships"}'>
  <img src="images/harbour/world-09-480.webp" alt="Boats Ships">
</a>
<!-- ...more links in the "harbour" group -->

A single image

A link without a group opens on its own: no counter, arrows or strip.

Twisting building facade
<a href="tower.webp" data-supermodal
   data-title="Twisting building facade"
   data-caption="Photo by Pavel Fertikh, CC0.">
  <img src="tower-960.webp" alt="Twisting building facade">
</a>

From JavaScript

Open any list of images, with or without links on the page. This one starts the slideshow.

SuperModal.open([
  { src: 'polar-lights.webp', title: 'Green and red polar lights' },
  { src: 'light-trails.webp', title: 'Neon light trails in Munich' },
  { src: 'spiral-stairs.webp', title: 'Spiral staircase' }
], 0, { autostart: true, interval: 3 });

document.addEventListener('supermodal:change', (e) => {
  console.log(e.detail.index, e.detail.item.title);
});

A page in the modal

Frame mode opens a page of your site in an iframe with the same look: a picker, a form, a video.

SuperModal.frame('picker.html', { title: 'Choose an image' });

// in picker.html, when the visitor is done:
parent.SuperModal.close();

Markup written for another lightbox

These links were written for FancyBox. With compat mode on (this page turns it on), SuperModal opens them as they are.

Water, Light and long shutter speeds Desktop purple neon light Coding workstation
<script>window.SuperModalDefaults = { compat: true };</script>

<a href="night.webp" data-fancybox="old"
   data-caption="Written for FancyBox">
  <img src="night-960.webp" alt="">
</a>

Install

Two files, no build step. Every release keeps its own address, so a page that loads dist/1.0.0/ never changes under you; dist/latest/ always has the newest release.

<link rel="stylesheet" href="https://fevangelou.github.io/supermodal.js/dist/1.0.0/supermodal.min.css">
<script src="https://fevangelou.github.io/supermodal.js/dist/1.0.0/supermodal.min.js" defer></script>

Or download supermodal.min.js and supermodal.min.css from the dist folder on GitHub and host them yourself. The readable sources are next to them.

Then add data-supermodal to the links of your images. Use the same name for the links of one gallery:

<a href="photos/beach.jpg" data-supermodal="holiday"
   data-title="The beach" data-caption="Day one, <b>early</b> morning">
  <img src="photos/beach-small.jpg" alt="The beach">
</a>
<a href="photos/harbour.jpg" data-supermodal="holiday">
  <img src="photos/harbour-small.jpg" alt="The harbour">
</a>

That's all. Links added later, for example by infinite scrolling, work too: SuperModal listens for clicks on the whole page.

Reference

Everything SuperModal reads from your markup, the options, the JavaScript API, its events and the CSS variables you can change.

Markup

AttributeOnWhat it does
data-supermodala link

Opens the link's image in the modal. The value is a group name ("holiday"): links with the same name form a gallery. Leave it empty for a single image, or give JSON with any of group, title, caption, srcset, thumb, download, html and the gallery options below.

data-titlea linkTitle shown above the caption.
data-captiona linkCaption; HTML allowed (links, emphasis, lists) and cleaned. Without it, the link's title is used.
data-srcseta linkA srcset for the full-screen image, e.g. "a-960.webp 960w, a.webp 1920w".
data-thumba linkImage for the thumbnail strip and the grid view. Default: the link's <img>, else the image itself.
data-downloada linkShows a download button for this file.
data-supermodal-itemany elementJSON with a src and a group: an image that belongs to a gallery but has no link on the page. These come first in the gallery.
<template class="supermodal-html" data-supermodal-for="holiday">the pageExtra HTML shown under every image of that gallery, such as a credit line. Scripts in it are removed.
data-supermodal-gallerya containerCompat mode: groups links that only have another lightbox's class (.swipebox, .highslide...) per container instead of per page.

Options

Set them for the page with SuperModal.setDefaults(), or in window.SuperModalDefaults before the script loads. theme, thumbs, loop, autostart and interval can also be set per gallery, in the JSON of its first link, or per SuperModal.open() call.

OptionDefaultWhat it does
theme'dark''dark' or 'light'.
thumbstrueShows the thumbnail strip under the image.
looptrueGoes from the last image back to the first.
autostartfalseStarts the slideshow when the modal opens.
interval5Seconds per image in the slideshow.
compatfalseAlso opens links written for other lightboxes: data-fancybox, data-lightbox, Fresco, Strip, Lightview, Nivo, rel="prettyPhoto[…]", rel="lightbox[…]", Colorbox, Swipebox, Highslide, Magnific Popup. Only links to image files.
stringsEnglishButton labels and messages: close, prev, next, play, pause, zoom, grid, download, fullscreen, more, counter ('Image {i} of {n}'), loading, error.

JavaScript

MethodWhat it does
SuperModal.open(items, index, options)

Opens a gallery at index. items is a CSS selector, a list of links, or an array of objects with src and optionally srcset, thumb, title, caption, download, html. options takes the options above and trigger, the element that gets the focus back on close. Returns false when there's nothing to show.

SuperModal.close()Closes the modal (and frame mode).
SuperModal.next(), prev(), goTo(index)Moves through the open gallery.
SuperModal.isOpen()Whether the modal is open.
SuperModal.frame(url, { title })Opens a page of your site in an iframe with the modal's look.
SuperModal.setDefaults(options)Changes the options for everything opened afterwards.

Events

Dispatched on document; the details are in event.detail.

EventWhenDetail
supermodal:openThe modal opened.index, item, items
supermodal:changeAnother image is shown.index, item, items
supermodal:closeThe modal closed.index, item

Keyboard and gestures

InputWhat it does
Left and right arrows, swipe sidewaysPrevious and next image.
Home, EndFirst and last image.
SpaceStarts or pauses the slideshow.
Z, double click, double tap, pinch, Ctrl + wheelZooms in and out; drag to pan.
GShows or hides the grid view.
EscLeaves the zoom, the grid view or the phone menu first, then closes.
Swipe down, the Back buttonCloses.

Styling

Change any of these variables on .supermodal, or on .supermodal--light for the light theme only:

.supermodal {
    --sm-accent: #0a7cff;   /* active buttons, focus, slideshow progress */
    --sm-bg: rgba(16, 16, 18, .985);
    --sm-fg: #f2f2f2;
    --sm-muted: #a8a8ad;
    --sm-btn-bg: rgba(255, 255, 255, .08);
    --sm-btn-bg-hover: rgba(255, 255, 255, .18);
    --sm-font: inherit;
    --sm-font-size: 15px;
    --sm-bar-height: 52px;
    --sm-btn-size: 40px;
    --sm-stage-pad: 56px;   /* room for the arrows beside the image */
    --sm-thumb-size: 56px;
    --sm-grid-gap: 8px;
    --sm-radius: 4px;
    --sm-duration: .25s;
    --sm-easing: cubic-bezier(.2, .7, .2, 1);
}

SuperModal works in the current versions of Chrome, Edge, Firefox and Safari, on desktops and phones.