Lightbox

Pro

A full-screen image viewer in five layouts. Each trigger registers its own image, the photo unmasks out of the tile, and every layout pages, zooms to a point and drags down to close.

Installation#

# One-time setup (tokens + lib helpers)npx koalaui-cli@latest init# Activate your Pro license (once per machine)npx koalaui-cli@latest login <key># Add this component (its dependencies come along)npx koalaui-cli@latest add lightbox

Usage#

This example is part of Koala UI Pro

The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.

Have a license? Unlock it here

Anatomy#

import {  Lightbox,  LightboxActions,  LightboxCaption,  LightboxClose,  LightboxContent,  LightboxCounter,  LightboxFooter,  LightboxHeader,  LightboxMeta,  LightboxNext,  LightboxPanel,  LightboxPrev,  LightboxRail,  LightboxThumbnails,  LightboxTrigger,  LightboxViewport,  LightboxZoom,  LightboxZoomIn,  LightboxZoomLevel,  LightboxZoomOut,} from "@/components/ui/lightbox"<Lightbox layout="stage">  <LightboxTrigger src="…" alt="…" />  <LightboxContent>    <LightboxViewport>      <LightboxPrev />      <LightboxNext />    </LightboxViewport>    <LightboxCaption />    <LightboxHeader>      <LightboxCounter />      <LightboxActions>        <LightboxZoomOut />        <LightboxZoomLevel />        <LightboxZoomIn />        <LightboxClose />      </LightboxActions>    </LightboxHeader>  </LightboxContent></Lightbox>

Stage#

The default. The photo alone on black: the counter top left, zoom and close top right, one caption line under the photo. Each side half of the photo pages, with a chevron that shows near the edge as the pointer moves. The chrome hides after two idle seconds, and a tap on the photo toggles it on touch.

The stop-at-the-ends viewer with its neighbours in view: the previous and next photos rest at the sides, smaller and dimmed, with a wide gap. As you drag, the one coming in grows and brightens on its way to the centre while the one leaving shrinks and dims. Click a neighbour to go to it. It stops at the first and last photo unless you pass loop.

Filmstrip#

One continuous track with the neighbours peeking on both sides. The strip below moves with it one to one: drag or wheel the strip and the photo scrubs along, and a flick carries on to the nearest slide. The caption and counter share one quiet line under the photo.

Inspector#

A detail view on the page's own theme. The photo sits on an inset stage and a side column carries the caption, dimensions, the pager, every image and a zoom toolbar with the level in figures. Under 768px the column becomes a bottom sheet you can drag between peek, full and hidden.

Feed#

A vertical stream instead of a pager: every image at one width with its caption, snapping to the one you opened. The rail on the right shows where you are and scrubs. Pull past the top of the first image to close, and zoom lifts the current image into a full-bleed pan layer.

Zoom#

Every layout zooms to a point by default, with zoom out, the level and zoom in in the corner: each press adds ten points of the fitted size (zoomStep), up to 300% (maxZoom). While zoomed the photo stays inside its band, under the header, and the controls sit on a dark pill. Set zoomable to false for images that gain nothing from it, like screenshots at their real size: the gestures, keys and controls go, and a click pages at once.

Thumbnails#

thumbnails decides whether the default viewer shows the other images. The stage leaves them out unless you turn it on, and then docks the same strip as the filmstrip under the caption, giving up photo height for it. The filmstrip and the inspector show them unless you turn it off.

Data mode#

For virtualised or CMS galleries, pass slides and drive open and index yourself. No trigger is needed; any LightboxTrigger index you do render becomes the flight origin and focus target for its slide.

Last seen: 1 of 6

Droppable parts#

Give LightboxContent children and only those render. Every part keeps its place whichever of its neighbours you leave out, and a part with no meaning in a layout renders nothing there.

Stop at the ends#

Paging loops by default. Set loop to false when the order means something, like the steps of a guide: the control at each end goes, and a drag past it resists and springs back.

Labels#

Every word the viewer shows or announces comes from labels. Pass the keys you want to change; the indexed ones receive the 0-based index and the total.

Wrap a Gallery tile in a LightboxTrigger with asChild and give the GalleryItem an action label for its pill.

This example is part of Koala UI Pro

The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.

Have a license? Unlock it here

API reference#

Lightbox

The root. Holds the slides, the index and the open state, and renders the viewer over Radix Dialog (focus trap, scroll lock, Esc, focus back to the current slide's trigger). Without a LightboxContent it renders the layout's default viewer.

PropTypeDefaultDescription
layout"stage" | "carousel" | "filmstrip" | "inspector" | "feed""stage"How the viewer looks and moves.
slidesLightboxSlide[]-Data mode: the slides, for galleries without a trigger per image. { src, thumb?, alt?, caption?, width?, height? }.
openboolean-Controlled open state.
defaultOpenbooleanfalseMounts already open, at rest, with no opening animation.
onOpenChange(open: boolean) => void-Called when the viewer opens or closes.
indexnumber-Controlled current slide. Changing it while open moves the viewer there.
defaultIndexnumber0The slide shown first, uncontrolled.
onIndexChange(index: number) => void-Called as the current slide settles on a new index.
loopbooleantrue (carousel: false)Wraps paging at the ends. false stops at the first and last slide: the end control goes and a drag rubber-bands.
labelsPartial<LightboxLabels>-Translatable copy. Missing keys keep their English defaults.
thumbnailsbooleanstage false, others trueWhether the layout's default parts include the thumbnails: a strip under the photo (stage, carousel, filmstrip) or the list in the panel (inspector). No effect on the feed, and children of LightboxContent always win.
zoomablebooleantrueZoom at all. false turns off double-click, pinch, ctrl and wheel and the + - 0 keys, hides every zoom control, and makes a single click page or close at once instead of waiting for a possible double-click.
maxZoomnumber3How far zoom reaches, as a multiple of the fitted photo (3 is 300%). A source with more pixels zooms further, up to its natural size. A double-click goes to 200% at the pointed spot.
zoomStepnumber0.1What one zoom button press or + / - key adds, as a fraction of the fitted photo: 0.1 reads 100%, 110%, 120% up to the cap; zoomStep={0.25} reads 125%, 150%, 175%. Double-click, pinch and wheel stay continuous.
flightbooleantrueUnmasks the photo out of its trigger and lands it back in the current slide's trigger on close. Off, off-screen or with reduced motion, the viewer crossfades.
imagesLightboxSlide[]-Deprecated alias of slides, kept for <LightboxTrigger index> galleries.
zoomboolean-Deprecated alias of flight.
rippleboolean-Deprecated and ignored: nothing behind the viewer moves.

LightboxTrigger

A tile that opens the viewer at its slide. Bare at rest; on hover and focus a scrim and a centred pill. It never moves or scales. Renders a <button> and forwards its props.

PropTypeDefaultDescription
srcstring-Registers this trigger's slide: the tile image, also the thumb while the full one loads. Without children the trigger draws it.
fullSrcstring-The full-size image the viewer shows. Defaults to src.
altstring-The image's alt text, also the trigger's name when it has no children.
captionReact.ReactNode-Shown by LightboxCaption, the inspector's thumb list and the feed.
width / heightnumber-Natural size. Optional, read from the image otherwise, but setting it shapes the frame before the photo loads.
indexnumber-Opens the root's slides (or images) at this position instead of registering a slide.
labelReact.ReactNode"See image"The pill. null hides it; ignored with asChild.
asChildbooleanfalseMakes the child the trigger (a GalleryItem, say). It draws no pill.

LightboxContent

Portal, ground and dialog. Without children it renders the layout's default parts; with children, only those. Accepts className, merged last.

LightboxViewport

The photos: one continuous track (stage, filmstrip, inspector) or the feed column. Children sit over it, like LightboxPrev and LightboxNext. Accepts className, merged last.

LightboxHeader

The top row, with no fill: whatever comes first sits left, LightboxActions sits right. Accepts className, merged last.

LightboxActions

A loose ghost ButtonGroup (2px) for zoom and close. Accepts className, merged last.

LightboxCounter

3 / 6, in tabular figures. Hidden with one slide. Accepts className, merged last.

LightboxClose

Icon button, Esc in its tooltip. Accepts className, merged last.

LightboxZoom

Kept for compatibility: a toggle with a fading % readout (stage), a toggle (filmstrip, feed) or a toolbar with zoom out, level, zoom in and fit (inspector). Accepts className, merged last.

LightboxZoomIn / LightboxZoomOut

Explicit zoom steps: in or out by zoomStep of the fitted photo (10 points by default) around its centre, from fit up to the cap (maxZoom, or natural size when larger). Disabled at either limit, + and − in their tooltips. The stage and carousel put them in the actions with the level between. Accepts className, merged last.

LightboxZoomLevel

The zoom level in tabular figures, counted from the fitted photo: fit reads 100%, each step adds zoomStep (110%, 120% by default) up to maxZoom (300% by default) or the image's natural size, whichever is larger. Nothing in the feed. Accepts className, merged last.

LightboxPrev / LightboxNext

Stage: each side half of the photo is a paging zone with a quiet chevron. Carousel and filmstrip: chips at the edges, centred on the photo. Inspector: ghost buttons. Feed: nothing. Gone at the ends with loop={false}. Accepts className, merged last.

LightboxCaption

Stage: one line under the photo. Filmstrip: the footer line. Inspector: title and alt. Feed: captions sit under every image instead. Accepts className, merged last.

LightboxThumbnails

Filmstrip: a strip coupled 1:1 with the track (drag it to scrub). Inspector: the list in the panel. Accepts className, merged last.

LightboxFooter

Filmstrip: the ground under the photo, holding the strip and caption line. Hidden while zoomed. Accepts className, merged last.

LightboxPanel

Inspector: the side column, a bottom sheet under 768px. Accepts className, merged last.

LightboxMeta

Inspector: dimensions and aspect of the current image. Accepts className, merged last.

LightboxRail

Feed: one tick per image on the right edge, the current one lit. Drag it to scrub. Accepts className, merged last.

LightboxLabels

viewer, close, previous, next, zoomIn, zoomOut, fit, zoomLevel, thumbnails, dimensions, aspect, position and trigger are strings; goToImage, imageOf and counter are (index, total) => string.

FAQ#

Stage for a quiet, photo-first viewer; carousel when the order matters and people should see what comes before and after; filmstrip when people scan a set and want to see what is next; inspector for assets where dimensions and a precise zoom level matter; feed for a story or a long set read top to bottom.