Lightbox Gallery

Project one or more ply-lightbox-thumb images into ply-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.

free

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

<ply-lightbox>
  <img
    ply-lightbox-thumb
    src="thumb.jpg"
    fullSrc="full.jpg"
    alt="Laptop"
    class="aspect-video w-full max-w-xl cursor-pointer rounded-xl object-cover"
  />
</ply-lightbox>

TypeScript

import { Component } from '@angular/core';

// Install: npx ply-ui-cli add lightbox
// Paths are relative to aliases.components (default: src/app/components)
import { LightboxThumbDirective } from './lightbox/lightbox-thumb.directive';
import { LightboxComponent } from './lightbox/lightbox.component';

@Component({
  selector: 'app-lightbox-example',
  imports: [
    LightboxComponent,
    LightboxThumbDirective
  ],
  template: `...`
})
export class LightboxExampleComponent {}

Install

bash

npx ply-ui-cli add lightbox

Multi grid (Tailwind size & ratio)

Put layout classes on ply-lightbox (applied to the thumbs wrapper). Each thumb keeps its own ratio — square, video, or portrait.

HTML

<ply-lightbox class="grid grid-cols-2 gap-3 sm:grid-cols-3">
  <img
    ply-lightbox-thumb
    src="…"
    fullSrc="…"
    alt="…"
    class="aspect-square w-full cursor-pointer rounded-lg object-cover"
  />
  <!-- more thumbs -->
</ply-lightbox>

TypeScript

import { Component } from '@angular/core';

// Install: npx ply-ui-cli add lightbox
// Paths are relative to aliases.components (default: src/app/components)
import { LightboxThumbDirective } from './lightbox/lightbox-thumb.directive';
import { LightboxComponent } from './lightbox/lightbox.component';

@Component({
  selector: 'app-lightbox-example',
  imports: [
    LightboxComponent,
    LightboxThumbDirective
  ],
  template: `...`
})
export class LightboxExampleComponent {}

Install

bash

npx ply-ui-cli add lightbox

Mixed ratios

Mix Tailwind aspect utilities on individual thumbs in the same gallery.

HTML

<ply-lightbox class="flex flex-wrap gap-3">
  <img ply-lightbox-thumb … class="aspect-square h-28 w-28 object-cover" />
  <img ply-lightbox-thumb … class="aspect-video h-28 w-48 object-cover" />
  <img ply-lightbox-thumb … class="aspect-3/4 h-28 w-20 object-cover" />
</ply-lightbox>

TypeScript

import { Component } from '@angular/core';

// Install: npx ply-ui-cli add lightbox
// Paths are relative to aliases.components (default: src/app/components)
import { LightboxThumbDirective } from './lightbox/lightbox-thumb.directive';
import { LightboxComponent } from './lightbox/lightbox.component';

@Component({
  selector: 'app-lightbox-example',
  imports: [
    LightboxComponent,
    LightboxThumbDirective
  ],
  template: `...`
})
export class LightboxExampleComponent {}

Install

bash

npx ply-ui-cli add lightbox

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

<ply-lightbox class="flex flex-wrap gap-3">
  <img
    ply-lightbox-thumb
    src="https://cdn.example/missing.jpg"
    alt="Jane Doe"
    class="aspect-square h-28 w-28 rounded-md object-cover"
  />
</ply-lightbox>

TypeScript

import { Component } from '@angular/core';

// Install: npx ply-ui-cli add lightbox
// Paths are relative to aliases.components (default: src/app/components)
import { LightboxThumbDirective } from './lightbox/lightbox-thumb.directive';
import { LightboxComponent } from './lightbox/lightbox.component';

@Component({
  selector: 'app-lightbox-example',
  imports: [
    LightboxComponent,
    LightboxThumbDirective
  ],
  template: `...`
})
export class LightboxExampleComponent {}

Install

bash

npx ply-ui-cli add lightbox

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

<!-- Optional toggles -->
<ply-lightbox
  [loop]="true"
  [showToolbar]="true"
  [showCounter]="true"
  [closeOnBackdrop]="true"
  [initialsFallback]="true"
  dialogLabel="Photo gallery"
  (opened)="onOpened($event)"
  (closed)="onClosed()"
  (indexChange)="onIndex($event)"
>
  …
</ply-lightbox>

TypeScript

import { Component } from '@angular/core';

// Install: npx ply-ui-cli add lightbox
// Paths are relative to aliases.components (default: src/app/components)
import { LightboxThumbDirective } from './lightbox/lightbox-thumb.directive';
import { LightboxComponent } from './lightbox/lightbox.component';

@Component({
  selector: 'app-lightbox-example',
  imports: [
    LightboxComponent,
    LightboxThumbDirective
  ],
  template: `...`
})
export class LightboxExampleComponent {}

Install

bash

npx ply-ui-cli add lightbox

Installation

Run the following command to add this component to your project:

bash

npx ply-ui-cli add lightbox

API Reference

For AI agents

Copy a prompt with the registry name, CLI install, and import — or add the Ply MCP server.

bash

npx -y ply-ui-mcp

Ply provides standalone components. Import the exact elements you want to use into your component.

typescript (Example)

// Install: npx ply-ui-cli add lightbox
// Paths are relative to aliases.components (default: src/app/components)
import { LightboxThumbDirective } from './lightbox/lightbox-thumb.directive';
import { LightboxComponent } from './lightbox/lightbox.component';

@Component({
  selector: 'app-your-component',
  imports: [
    LightboxComponent,
    LightboxThumbDirective
  ],
  template: `...`
})
export class YourComponent {}

API for lightbox — generated from JSDoc in the library source.

API reference for lightbox
API	Member	Type	Default	Description
`ply-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.
`ply-lightbox`	`loop`	`boolean`	`true`	When true, prev/next wrap around the ends of the gallery.
`ply-lightbox`	`showToolbar`	`boolean`	`true`	Whether to show the transform / download toolbar.
`ply-lightbox`	`showCounter`	`boolean`	`true`	Whether to show the "n / total" counter when there is more than one image.
`ply-lightbox`	`closeOnBackdrop`	`boolean`	`true`	Close the overlay when the backdrop is clicked.
`ply-lightbox`	`dialogLabel`	`unknown`	`'Image lightbox'`	Accessible name for the lightbox dialog.
`ply-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.
`ply-lightbox`	`(opened)`	`number`	—	Emitted when the lightbox opens, with the active index.
`ply-lightbox`	`(closed)`	`void`	—	Emitted when the lightbox closes.
`ply-lightbox`	`(indexChange)`	`number`	—	Emitted whenever the active image index changes while open.
`[ply-lightbox-thumb]`	`fullSrc`	`string`	`''`	Optional full-resolution URL shown in the overlay. Falls back to the element's native `src` (or `imageSrc`) when omitted.
`[ply-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.
`[ply-lightbox-thumb]`	`imageAlt`	`string`	`''`	Accessible label override for non-`<img>` hosts. On `<img>`, use native `alt`.
`[ply-lightbox-thumb]`	`downloadName`	`string`	`''`	Suggested filename for the download action.
`[ply-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").

Ply — ply-ui.com — is a CLI-first Angular + Tailwind CSS component library with 215 components and blocks (125 free), delivered shadcn-style: npx ply-ui-cli add copies the TypeScript/HTML source into your project, where you own and edit it. There is no npm library package. Not MUI Base UI (base-ui.com, React).