Espalier components → Lightbox

import "@taprootio/espalier/lightbox";

<esp-lightbox>

A full-screen lightbox for viewing high-res versions of esp-image elements. Point the for attribute at a CSS selector for the container that holds the images. Clicking any image in that container opens the lightbox at that image.

A field fills one layer above the surface it sits on. Use surface-layer="1|2|3|4" to select the default painted layer.

On mobile, swipe left or right to navigate. The gallery wraps around — swiping past the last image goes back to the first.

A subtle caret at the bottom of the screen reveals a drawer overlay containing the image caption and a comments slot.

Both halves of that panel are optional. hide-comments drops the comment count and the comments slot; hide-caption drops the image caption. With only the caption left, the bar shows it on one line and slides up only when the line is actually clipped — a caption that already fits has no caret and no tab stop. With both hidden there is no bar, though navigation dots remain for a multi-image gallery.

Slots

<esp-lightbox> has a slot:

comments

A slot for comments UX, rendered inside a collapsible drawer.

Attributes

<esp-lightbox> has the following attributes:

for

for has a default value of "".

A CSS selector for the container element that holds the esp-image elements to include in the lightbox.

comment-count

comment-count has a default value of 0.

The number of comments to display in the comment bar.

hide-comments

hide-comments has a default value of false.

Remove the comment affordance: no comment count, no caret driven by it, and no comments slot. The caption can still open a drawer when it is too long for one line.

hide-caption

hide-caption has a default value of false.

Remove the image caption from the bar and the drawer.

surface-layer

surface-layer has a default value of undefined.

Declares the painted surface depth. Fields use the next local layer, capped at layer 4.

intent

intent has a default value of undefined.

The element's intent — its meaning: neutral (no pin), or success, warning, danger, info — each pinned to its fixed status family (blue for info), retunable per theme via intents. On token-emitting controls a non-neutral intent pins the filled-action pair to that family, derived over the governing zone's theme; class-styled chrome (badges, callouts, status pills) opts out of inline emission and renders its treatment from CSS classes instead. An intent never repaints the surrounding zone, which is what contexts are for. Removing the attribute restores the element's own default intent.

context

context has a default value of undefined.

A theme-defined color zone. The selected context rebinds designer-facing roles and emits a complete, contrast-enforced semantic token table on this host for descendants to inherit.

Methods

<esp-lightbox> has the following methods:

open

Open the lightbox at the given image index.

close

Close the lightbox.

traverseToClosest

Traverse up the DOM tree to find the closest element that matches the selector. This method is aware of shadow DOM boundaries and will traverse through them to find the element.

Events

<esp-lightbox> emits the following events:

esp-lightbox-changed is of type CustomEvent<{ index: number }>.

Fired when the displayed image changes — on open, navigation (prev/next buttons, keyboard arrows, swipe, dot click). The index in the detail is the zero-based position of the now-visible image in the source container.

CSS Properties

<esp-lightbox> has the following CSS properties:

The background color of the lightbox overlay (falls through to --esp-vellum-background, then --esp-color-layer-3).

The opacity of the overlay background (falls through to --esp-vellum-opacity, default: 0.85).

--esp-vellum-background-image

Optional repeating background image for the overlay (default: none).

--esp-vellum-background-image-opacity

Opacity of the background image layer (default: 0.3).

--esp-field-background

Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at var(--esp-color-layer-4), or var(--esp-color-layer-2) without a declared surface. An explicit override wins.

--esp-field-border-color

Border color of the shared field shell. Defaults to var(--esp-color-border).

--esp-field-border-width

Border width of the shared field shell. Defaults to 1px.

--esp-field-text-color

Text color used inside the shared field shell. Defaults to var(--esp-color-text).

--esp-field-hover-bg

Hover background color of the shared field shell. Derived from --esp-field-background.

--esp-field-focus-bg

Focus background color of the shared field shell. Derived from --esp-field-background.

--esp-field-focus-shadow

Shadow color used for shared field focus treatment. Defaults to var(--esp-color-shadow).