Lightbox Gallery
Project one or more base-lightbox-thumb images into base-lightbox. Thumb size and aspect ratio are controlled with Tailwind on each image. Click a thumb to open a focus-trapped overlay with flip, rotate, zoom, download, and fullscreen tools.
Single image
A single thumb works the same way — no prev/next controls appear. Use Tailwind for ratio and max width on the thumb itself.
HTML
Multi grid (Tailwind size & ratio)
Put layout classes on base-lightbox (applied to the thumbs wrapper). Each thumb keeps its own ratio — square, video, or portrait.
HTML
Mixed ratios
Mix Tailwind aspect utilities on individual thumbs in the same gallery.
HTML
Broken image → alt initials
If a thumb (or the overlay image) fails to load, initials are taken from alt — e.g. "Jane Doe" → JD, "Coast" → CO. Disable with [initialsFallback]="false" on the thumb or the lightbox.
HTML
Toolbar
Open any gallery above to use the toolbar: horizontal/vertical flip, rotate 90°, zoom in/out (mouse wheel too), download, and browser fullscreen. Keyboard: Esc closes, ←/→ navigate, +/− zoom.
HTML
Installation
Run the following command to add this component to your project:
bash
npx base-ui-cli add lightbox
API Reference
Base UI provides standalone components. Import the exact elements you want to use into your component.
typescript (Example)
import { LightboxComponent, LightboxThumbDirective } from '@lussos/base-ui';
@Component({
selector: 'app-your-component',
imports: [
LightboxComponent,
LightboxThumbDirective
],
template: `...`
})
export class YourComponent {} Properties for lightbox — generated from JSDoc in the library source.
| Selector | Property | Type | Default | Description |
|---|---|---|---|---|
[base-lightbox-thumb] | fullSrc | string | '' | Optional full-resolution URL shown in the overlay. Falls back to the element's native `src` (or `imageSrc`) when omitted. |
[base-lightbox-thumb] | imageSrc | string | '' | Image URL for non-`<img>` hosts. Do **not** use this on `<img>` — bind the native `src` attribute instead so the thumbnail is visible. |
[base-lightbox-thumb] | imageAlt | string | '' | Accessible label override for non-`<img>` hosts. On `<img>`, use native `alt`. |
[base-lightbox-thumb] | downloadName | string | '' | Suggested filename for the download action. |
[base-lightbox-thumb] | initialsFallback | boolean | true | When true (default), a broken or missing image is replaced by initials derived from `alt` / `imageAlt` (e.g. "Jane Doe" → "JD"). |
base-lightbox | class | string | '' | Classes for the thumbs layout wrapper (e.g. `grid grid-cols-3 gap-2`). Applied to an inner container so projected thumbs participate in that layout. |
base-lightbox | loop | boolean | true | When true, prev/next wrap around the ends of the gallery. |
base-lightbox | showToolbar | boolean | true | Whether to show the transform / download toolbar. |
base-lightbox | showCounter | boolean | true | Whether to show the "n / total" counter when there is more than one image. |
base-lightbox | closeOnBackdrop | boolean | true | Close the overlay when the backdrop is clicked. |
base-lightbox | dialogLabel | unknown | 'Image lightbox' | Accessible name for the lightbox dialog. |
base-lightbox | initialsFallback | boolean | true | When true (default), a broken or missing viewer image shows initials from the thumb's `alt` / `imageAlt` instead of an empty stage. |
base-lightbox | (opened) | number | — | Emitted when the lightbox opens, with the active index. |
base-lightbox | (closed) | void | — | Emitted when the lightbox closes. |
base-lightbox | (indexChange) | number | — | Emitted whenever the active image index changes while open. |
Content