Skip to content
Pelatform UI

Data display

Lightbox

Opens linked images in a full-screen viewer, one at a time or as a gallery, with captions, keys and swipes.

Class nameTypeDescription
lightboxplf:lightboxComponentThe full-screen viewer the script adds
lightbox-counterplf:lightbox-counterPartThe image number the script adds
lightbox-closeplf:lightbox-closePartThe close button the script adds
lightbox-imageplf:lightbox-imagePartThe full image the script adds
lightbox-loadingplf:lightbox-loadingPartThe spinner the script shows while an image loads
lightbox-errorplf:lightbox-errorPartThe message the script shows when an image cannot load
lightbox-captionplf:lightbox-captionPartThe caption the script adds from the image's alt text
lightbox-controlplf:lightbox-controlPartA round previous or next button the script adds
lightbox-control-previousplf:lightbox-control-previousModifierThe previous button
lightbox-control-nextplf:lightbox-control-nextModifierThe next button

Default

A palm tree on a sunny beach

Gallery

A palm tree on a sunny beach Pine trees below green hills City towers at sunset Desert dunes A garden in bloom An event venue

Open from a script

Hidden links still join the gallery: three photos show, and the script’s open() opens all six from the first; open(index) starts at another.

Carousel

A palm tree on a sunny beach
Pine trees below green hills
City towers at sunset

JavaScript

Lightbox needs JavaScript. Without it, and inside an open Modal, where dialogs do not stack, each link opens its image itself. The Full script (pelatform-ui.min.js) starts every component on page load, with no code of your own; with ESM imports, call init() yourself, as in Installation. For markup you add later, see Dynamic content.

<link rel="stylesheet" href="pelatform-ui.min.css">
<script src="pelatform-ui.min.js" defer></script>
<link rel="stylesheet" href="pelatform-ui.prefixed.min.css">
<script src="pelatform-ui.min.js" defer></script>

Hooks

Attribute Purpose
data-plf-lightbox On a link, opens its image in the viewer; on another element, its links that hold an <img>, hidden ones included, open as one gallery, in page order. Each caption is the image’s alt text, which every link needs
data-plf-close-label, data-plf-previous-label, data-plf-next-label On the lightbox, the button names; Close, Previous image and Next image by default
data-plf-counter-label What a screen reader hears after the caption; {index} of {count} by default
data-plf-error-label, data-plf-open-label The message and its link when an image cannot load; The image could not load. and Open image by default

Methods

Method Behavior
PLF.Lightbox.getOrCreateInstance(element) Returns the instance, creating it for valid markup
PLF.Lightbox.getInstance(element) Returns the instance or null
instance.open(index) Opens the viewer at an image, counted from 0 (the first by default), or shows it while open; false when it cannot open
instance.close() Closes the viewer and gives focus back; false when it is not open
instance.next(), instance.previous() Show the next or previous image, without wrapping
instance.getState() Returns {open, index, count}
instance.destroy() Closes the viewer without events and removes listeners; the root’s last lightbox removes the viewer

Events

Event When
plf:lightbox:open After the viewer opens
plf:lightbox:change After the viewer shows another image
plf:lightbox:close After the viewer closes

Each event’s detail:

Property Events Value
instance All The Lightbox instance
index All The index of the image shown, counted from 0
trigger All The clicked link or button, or null from a key, a swipe, the backdrop or a method
reason All trigger for the link or the close button, previous, next, keyboard, swipe, backdrop or api
previous change The index of the image shown before

Keyboard

Key Action
Left Arrow, Right Arrow Show the previous or next image; mirrored right to left
Home, End Show the first or last image
Escape Close the viewer
Tab, Shift+Tab Move between the viewer’s buttons

React

Lightbox from @pelatform/react renders its children, whose LightboxLinks open their images as one gallery in page order, then the viewer on a Modal: it keeps its own state, or the application opens it with open and sets the image with index.

Prop Values Default
open true while the viewer is open, which the application changes in onOpenChange Its own state
onOpenChange (open, reason), called when a link opens the viewer (trigger) or the viewer asks to close: trigger (its close button), keyboard (Escape) or backdrop (a click beside the image) None
index The image shown, from 0, which the application changes in onIndexChange Its own state: the clicked link’s image, or the first
onIndexChange (index, reason), called when a link (trigger), a button (previous, next), a key (keyboard) or a swipe (swipe) shows another image None
closeLabel, previousLabel, nextLabel The button names Close, Previous image and Next image
counterLabel (index, count), what a screen reader hears after the caption, with the image’s number from 1 {index} of {count}
errorLabel, openLabel The message and its link when an image cannot load The image could not load. and Open image

The parts:

Part Element
LightboxLink An a to the full image (href), captioned with its image’s alt text; a click opens the viewer at it, and a hidden one still joins the gallery

The other props are the element’s own, className and ref included; Lightbox’s element is the viewer’s dialog.

CSS variables

Override on a root.

Variable Default
--plf-lightbox-bg The dark theme’s surface (neutral-950)
--plf-lightbox-color The dark theme’s text (neutral-50)
--plf-lightbox-image-radius Extra large radius (12px)

Built with Pelatform UIv0.1.0

Components

Getting started

Foundations

Components

Actions

Data display

Navigation

Feedback

Data input

Layout

Advanced

Integrations

Blocks

Application

Authentication

Icons