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.

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.

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.

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 var(--esp-color-layer-2).

--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).

Lightbox