Image Gallery with Lightbox Widget
Show your own photos as a tidy grid, uncropped masonry-style columns or a single swipeable strip. Visitors click any picture to open an accessible lightbox with a "3 of 12" counter, arrow-key browsing and an Esc-to-close dialog that hands focus back to the thumbnail.
Live preview
Under the widget on your page: Powered by A2Z Tools
Embed code
<iframe src="https://a2z.tools/embed/w/image-gallery" title="Image Gallery with Lightbox by A2Z Tools" width="100%" height="410" style="border:0;width:100%" loading="lazy" allow="clipboard-write"></iframe>
A plain iframe. Works everywhere, including site builders that strip scripts. Adjust height if your content needs more room.
<div data-a2z-widget="image-gallery" data-height="410"></div> <script async src="https://a2z.tools/embed.js"></script>
Adds a small script (what it does) that sizes the widget to fit its content, loads it lazily and keeps it isolated from your page's CSS.
Works with
How it works
Every line describes one picture: an https image address, a caption, the alt text and an optional link, separated by vertical bars. Writing the word sample instead of an address draws a gradient tile, which is how the default gallery renders without borrowing anyone's photos. Addresses that are not https - plain http, data:, javascript: or a relative path - are refused and shown as an "Image unavailable" tile, as is any photo whose server returns an error, so a deleted file never leaves a broken icon. Alt text comes from the third column; when that is empty the caption is used, and the literal word decorative gives alt="" on purpose. A photo with neither gets "Image 4 of 9" and a warning in the builder preview. Thumbnails load lazily with fixed width and height, so the frame does not jump. The lightbox is a modal dialog drawn inside the iframe: it covers the part of the frame the visitor can currently see, measured with IntersectionObserver, traps Tab between Previous, Next, Close and the optional link, wraps from the last photo to the first and supports swiping on phones.
Method
- Line format: https image URL | caption | alt text or "decorative" | optional link; "sample" in the first cell draws a gradient tile
- Alt text = alt cell, else caption, else "Image n of N" (flagged in the builder preview); "decorative" or "-" = alt=""
- Refused: any first cell that is not an https URL (http:, data:, javascript:, relative); load errors swap to an Image unavailable tile
- Lightbox keys: ArrowRight/ArrowLeft next/previous (wrapping), Home/End first/last, Esc close; Tab and Shift+Tab cycle inside the dialog
- Lightbox placement: top/height = the frame's visible band from IntersectionObserver, at least 320px or the whole frame if shorter
- Options: v_layout=grid|columns|strip, v_ratio=1x1|4x3|3x2|16x9|3x4, v_size=small|medium|large, v_captions=below|overlay|none, v_lightbox=on|off; at most 60 images
Worked examples
Mixed good and refused images
Inputs: Lines "https://example.com/door.jpg | Red door | A red front door with a brass knocker", "http://example.com/b.jpg | Garden", "javascript:alert(1) | Test"
Result: One real thumbnail with alt "A red front door with a brass knocker"; two "Image unavailable" tiles; the builder preview says 2 image addresses were refused
Only https images may load inside the frame, and javascript: never becomes a link or a source.
Keyboard tour of the lightbox
Inputs: 12 photos; open the 3rd, press ArrowRight twice, End, ArrowRight, Esc
Result: Counter reads 3 of 12, 5 of 12, 12 of 12, 1 of 12; Esc closes and focus returns to the 3rd thumbnail
Arrow keys wrap around the ends and focus is restored as the APG modal dialog pattern requires.
Decorative divider image
Inputs: https://example.com/flourish.png | | decorative
Result: Image rendered with alt="" and no warning
The explicit word decorative is the only way to get an empty alt.
Limitations
- The lightbox cannot cover your whole page; it fills the visible part of the widget's own frame.
- Photos are not uploaded, resized or stored by A2Z - they must already be online at an https address you control.
- No zoom, slideshow autoplay, video or image download button.
- In the columns layout the reading order runs down each column, not across the rows.
Where publishers use it
- A wedding photographer's Squarespace portfolio page with a six-picture grid that opens full size
- A holiday cottage listing on Wix showing bedrooms, kitchen and garden in uncropped masonry columns
- A restaurant's Instagram-style strip of plated dishes under the menu on a WordPress site
- A builder's project page linking each finished-job photo to its case study
- A school fete or charity run recap where volunteers' pictures are hosted on the school's own https server
Questions
Why does the lightbox open inside the widget area instead of over my whole page?
An iframe can only draw inside its own rectangle - a cross-site frame is not allowed to paint over your header or dim the rest of your page. The gallery therefore opens its dialog over the part of the frame the visitor can see right now, at least 320 pixels tall. For the most comfortable viewing keep a gallery to two or three rows on desktop (or use the strip layout); a 1,400-pixel-tall frame still works, but its lightbox only spans the visible slice of it.
Where do the photos have to be hosted?
Anywhere that serves them over https: your own website's media library, a CDN, or a storage bucket with public read access. The address must start with https:// and point at the image file itself (ending .jpg, .png, .webp or similar, or a CDN URL that returns an image). Page links to Google Photos albums or Dropbox previews are web pages, not images, and will show the Image unavailable tile.
What should I write as alt text?
Describe what the picture shows for someone who cannot see it, in about 5-15 words: "Oak dining table set for six in the conservatory" rather than "IMG_2041" or "photo". If the caption already says it, leave the alt column empty and the caption is used. Only write decorative for purely ornamental images - the W3C images tutorial says those take an empty alt so screen readers skip them.
Which layout should I choose?
Grid crops every thumbnail to the same ratio (4:3 by default) for a calm, even look; choose 1x1 for product shots or 3x4 for portraits. Columns keep each photo's own shape in 2-4 masonry-style columns, best for mixed portrait and landscape shots; reading order runs down each column. Strip puts everything in one sideways-scrolling row, which keeps the frame short - about 250 pixels at phone width.
Can a thumbnail link to another page instead of opening the lightbox?
Yes. Put the address in the fourth column. With the lightbox on, the enlarged view shows an "Open link" button; with v_lightbox=off each thumbnail becomes the link itself and opens in a new tab with rel=noopener nofollow. Only https, http, mailto and tel links are accepted.
Will large photos slow my page down?
Thumbnails use loading=lazy, so pictures below the fold are fetched only when scrolled near, and only the photo being viewed loads at full size in the lightbox. The widget does not resize or compress your files, though - upload web-sized images (around 1,600 pixels on the long side and under 400 KB) for fast pages.
Sources
- Dialog (Modal) Pattern - W3C WAI-ARIA Authoring Practices Guide . Tab/Shift+Tab stay inside the dialog, Escape closes it, focus returns to the invoking element, aria-modal=true. Checked 2026-10-01.
- Decorative Images - W3C Web Accessibility Initiative - Images Tutorial . Purely decorative images take a null alt (alt="") so assistive technologies ignore them. Checked 2026-10-01.
Cite or recommend this tool
If you reference this tool in an article, course or documentation, these formats are ready to copy. They are optional - nothing is added to your site unless you paste it.
A2Z Tools Image Gallery with Lightbox https://a2z.tools/embed/image-gallery
<a href="https://a2z.tools/embed/image-gallery">A2Z Tools Image Gallery with Lightbox</a>
[A2Z Tools Image Gallery with Lightbox](https://a2z.tools/embed/image-gallery)
Image Gallery with Lightbox by A2Z Tools - https://a2z.tools/embed/image-gallery
Related widgets
-
Drag-to-compare before and after photos with a keyboard slider, vertical mode and a side-by-side fallback.
-
A 'Trusted by' grid of client logos with text fallbacks, grayscale-to-colour and an optional pausable row.
-
Customer quotes as cards, a featured quote, a list or a manual slider, with stars and initials avatars.
-
Accessible FAQ accordion with search, expand-all, numbering and a copy-as-text button.
-
A vertical or sideways-scrolling timeline of dated milestones, with an optional Now marker.
-
Numbered How-it-works steps with drawn icons, or an order tracker that highlights the current step.