Expandable Image — wd-expandable-image

Category: Promo · Tag: wd-expandable-imageBack to: Components overview

---

What it does

A clickable image that expands into a full-screen lightbox when clicked: the page dims behind a shader and the image scales up to fit the screen. Perfect for product shots, galleries on dynamic pages, screenshots, and portfolio pieces. Closing is a click anywhere (the shader or the enlarged image) or Esc.

It takes no slotted content — everything comes from its settings.

---

Adding it & its settings

Add Component → Promo → Expandable Image.

Basic Settings (all components): #id, Classes, Inline Style.

Component Settings:

Setting	What it does
Image source (required)	Where the image comes from — three forms: a File Manager URL (/web-assets/<file name> — upload via the File Explorer and use its content URL), any absolute URL, or $$field to bind a dynamic-content field (see below).
Width / Height	CSS sizes for the inline image (300px, 100%, 12rem). Empty = the image's natural size. The expanded view ignores these — it always scales to fit the screen.
Alt text	Describes the image for screen readers and search engines. Also accepts $$field.

Dynamic sources ($$field)

On a dynamic page, set the source to $$ + the schema field name (e.g. $$product_photo) and each item renders its own image — same for the alt text ($$product_name). If the field is missing or empty, the component renders nothing at all (no broken-image icon on live pages) — that's intentional.

---

The lightbox

• Click the image → it expands over a dimmed shader, scaled to fit (max 90vw × 90vh by default).
• Close with a click anywhere — the shader or the enlarged image — or Esc.
• The page behind can't scroll while it's open (restored on close).
• It emits an imageExpanded event (detail.state: 1 opened, 0 closed).

---

Styling

CSS variables

Inline image

Variable	Default
--wd-expandable-image-display	inline-block
--wd-expandable-image-object-fit	cover
--wd-expandable-image-border-radius	0
--wd-expandable-image-box-shadow	none
--wd-expandable-image-cursor	zoom-in

Lightbox

Variable	Default
--wd-expandable-image-shader-background	rgba(0, 0, 0, 0.7)
--wd-expandable-image-shader-blur	0px (backdrop blur radius)
--wd-expandable-image-z-index	999
--wd-expandable-image-expanded-max-width	90vw
--wd-expandable-image-expanded-max-height	90vh
--wd-expandable-image-expanded-border-radius	0.25rem
--wd-expandable-image-expanded-box-shadow	0 8px 32px rgba(0,0,0,0.35)

/* example: rounded thumbnails with a frosted lightbox */
wd-expandable-image {
  --wd-expandable-image-border-radius: 0.75rem;
  --wd-expandable-image-box-shadow: 0 2px 8px rgba(0,0,0,.12);
  --wd-expandable-image-shader-blur: 4px;
}

::part()

Part	Element
expandable-image-<id>	The wrapper (inline image + shader + expanded image).

---

Notes

• A missing source renders nothing — if the image doesn't appear, check the source URL or the dynamic field name first.
• The width/height settings size the inline image only; use the expanded-max-* variables to change how large the lightbox lets it grow.
• Several expandable images can share a page (e.g. a gallery on a dynamic page) — each opens its own lightbox.