Lightbox
A full-screen viewer with zoom, pan, pinch, swipe, a thumbnail strip, a slideshow and complete keyboard control.
Click an image in a gallery and the lightbox opens it full-screen, with the rest of the gallery available left and right. It's on by default, and it's the click action most galleries want.
Settings live in two places, on purpose
This trips people up once, and then never again:
| Decision | Where it lives | Why |
|---|---|---|
| Does clicking this gallery open the lightbox, and is the trigger the whole tile or a badge? | The gallery's Image Click Action panel | It's a property of this gallery's design. |
| What does the badge look like, and how does the viewer behave? | Settings → Modules → Lightbox | It's site-wide, so you style your lightbox once. |
The viewer is a single element shared by every gallery on a page, so two galleries couldn't each have their own theme for it anyway.
Turning it on for a gallery
- Select the gallery.
- Open Image Click Action.
- Set Click Action Type to Lightbox.
- Choose Lightbox Click Action:
- Full Image — the whole tile is the trigger.
- Icon — a small badge on the tile is the trigger, and the rest of the tile is not clickable.
"Icon" really does mean only the icon
With Icon selected, the image itself is no longer a link. That's the setting's entire meaning — if you want both a badge and a fully clickable tile, use Full Image and style the badge to taste.
Not available on Thumbnails
The Thumbnails layout renders its main slides with no click action, so the lightbox can't open there and the Image Click Action panel isn't shown. Perspective keeps it — its tiles are ordinary lightbox links.
Site-wide settings
Shaped Gallery → Settings → Modules → Lightbox, then the gear on the card.
Lightbox Icon
| Setting | What it does |
|---|---|
| Lightbox Icon | Which glyph the badge uses — or Upload a custom icon for your own. |
| Lightbox Icon Style | The badge's colour, background and optional border. |
| Icon Display Position | Top Left, Top Right, Center, Bottom Left, Bottom Right. |
| Offset | Distance in pixels between the icon and the edge of the image. |
General Setting
| Setting | What it does |
|---|---|
| Lightbox Theme | Light Theme or Dark Theme. |
| Close When Click Outside | Close the viewer when the visitor clicks the backdrop. |
| Lightbox Slider Settings | A popover holding AutoPlay, Loop, Keyboard Navigation, and Slide Transition Effect (Fade, Slide, Tube, Zoom In-Out, Rotate, None). |
| Lightbox Transition Effect | How the viewer itself opens: Zoom, Fade, Slide, Circular, Tube, Zoom In-Out, Rotate, None. |
Lightbox Image and Thumbnails
| Setting | What it does |
|---|---|
| Image Caption | Show each image's caption and description inside the viewer. |
| Title | Show the image's title above the image. |
| Item Counter | Show the position of the current image, e.g. 3 / 12. |
| Lightbox Toolbar | A popover of individual buttons: Zoom, Full-Screen, Slideshow Play, Social Share, Download, Bottom Thumbnails Gallery Icon, Close. |
| Right Click Protection | Block the right-click menu on the lightbox image. |
Turn off what you don't want visitors doing
Download and Social Share are both off-switchable. Neither is a security control — anyone determined can still save an image — but removing the button removes the invitation. For something stronger, combine Watermark with Image Protection.
A toolbar button that's off is removed, not hidden
Switching a button off takes it out of the page entirely, so it can't be reached by keyboard or announced by a screen reader either. That's deliberate — a hidden-but-focusable control is worse than no control.
Using it
| Gesture | What it does |
|---|---|
| Click / tap an image | Open the viewer |
| Swipe, or drag | Previous / next image |
| Pinch, or the zoom button | Zoom in and out |
| Drag while zoomed | Pan around the image |
| Click the backdrop | Close (if Close When Click Outside is on) |
Keyboard
| Key | What it does |
|---|---|
| ← / → | Previous / next image |
| Home / End | First / last image |
| Esc | Close |
| Tab | Move between the toolbar's controls |
Because the viewer is a real modal dialog, the browser itself handles the focus trap, makes the page behind it inert, and closes on Escape — so keyboard behaviour is the platform's, not an approximation of it.
Things worth knowing
It's a separate download, requested only when needed. A page whose galleries all use None or URL as their click action never downloads the viewer at all — not the JavaScript and not the CSS. Neither does a page with only a Thumbnails gallery on it.
It sits above everything. The viewer opens in the browser's top layer, so a sticky header, a cookie banner or a chat widget can't cover it — and there's no z-index war to win.
Without JavaScript, the link still works. A lightbox trigger is a real link to the full-size file. If the script fails to load, clicking opens the image directly rather than doing nothing.
Switching the module off degrades gracefully. Turn Lightbox off in Modules and the badge, its CSS, the viewer bundle and the click binding all disappear — while the tile stays a link to the full-size image. Galleries set to Lightbox aren't broken by it, and their stored setting is untouched: switch the module back on and everything returns.
Slideshow pauses over the image. With AutoPlay on, resting the pointer on the photo pauses it. Moving the pointer over the toolbar or the backdrop doesn't — those are deliberate interactions and the show keeps running.
Perspective galleries work correctly. That layout clones tiles to loop its scroll; the viewer de-duplicates them, so clicking the third image opens the third image.
Troubleshooting
The lightbox doesn't open. Check three things in order: the module is on in Settings → Modules; the gallery's Click Action Type is Lightbox; and the layout isn't Thumbnails. If all three are fine, look for a JavaScript error from another plugin on the page.
Only the badge is clickable. That's Lightbox Click Action → Icon working as designed. Switch it to Full Image.
The theme's header shows through. It shouldn't — the viewer is in the top layer. If it does, something on the page is forcing the dialog out of it; check for a plugin that rewrites dialog elements.