Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Single picture

Show one photo at the full width of its container when a page needs a single image with its caption.

One picture with download
Front gate
Show code
<app-lightbox layout="Single" download="true">
    <app-lightbox-item src="/site/gate.webp" thumb="/site/gate-sm.webp" alt="Front gate" caption="Front gate, 12-Mar-2026" />
</app-lightbox>

Every option

Every value of every prop, one cell each.

items

<app-lightbox-item src alt>
Front gate
<app-lightbox-item thumb>
<app-lightbox-item caption>
Yard before levelling, 14-Mar-2026
<app-lightbox-item name>

download

download="true"
Front gate
download="false" (default)
Front gate

label

label="Image viewer" (default): read by screen readers only
Front gate

layout

layout="gallery" (default)
Front gateYard
layout="single"
Front gate

openIndex

open-index="2" (React: openIndex)
Front gateYardSite office

onChange

wui-lightbox:change (React: onChange): fires with detail.index, counted from 0
Front gateYardSite office

onClose

wui-lightbox:close (React: onClose): fires when the full-screen view closes
Front gateYardSite office

className

class (React: className): extra classes on the gallery, this demo adds none
Front gate

Guidance

What to do, and what to avoid.

Use it when

  • A gallery of photos.
  • Image attachments on a record that should open without leaving it.

Reach for something else when

  • A PDF, video or audio file. → AppFileViewer
  • One image that is part of the page's content. → a plain img

Reference

Try every prop, read the full list, and check keyboard and screen reader behaviour.

gallery single
Front gateYardSite office
React, generated from the controls
<AppLightbox items={photos} download label="Site photos" />
Razor, the same props
<app-lightbox download="true" label="Site photos">
    <app-lightbox-item src="/site/gate.webp" thumb="/site/gate-sm.webp" alt="Front gate" caption="Front gate, 12-Mar-2026" />
</app-lightbox>

12 props. The 4 most used come first.

Used on most screens 4 props

PropTypeDefaultDescription
downloaddefault false bool false Shows a download action. A browser ignores name for an image on another origin.
labeldefault Image viewer string Image viewer The full-screen dialog's name for screen readers.
layoutdefault gallery string gallery gallery shows thumbnails; single shows each image at the container's full width, at its own shape.
open-indexdefault - int - Opens the viewer on this image, counted from 0.

Less common 8 props

PropTypeDefaultDescription
<app-lightbox-item> srcdefault - string - The full image.
<app-lightbox-item> thumbdefault src string src The thumbnail.
<app-lightbox-item> altdefault caption string caption The image's text alternative.
<app-lightbox-item> captiondefault - string - The line under the image in the full-screen view.
<app-lightbox-item> namedefault last part of src string last part of src The file name a download saves under.
wui-lightbox:opendefault - event - Fires when the full-screen view opens, with detail.index for the image shown.
wui-lightbox:changedefault - event - Fires when the image shown changes, with detail.index; React's onChange is this event.
wui-lightbox:closedefault - event - Fires when the full-screen view closes, with detail.index; React's onClose is this event.

Screen reader

3 notes
  • Left and Right change image, wrapping at the ends; plus and minus zoom, 0 resets the zoom, and Escape closes and puts focus back on the thumbnail of the image last shown.
  • On a touch screen, swipe sideways to change image, pinch or double tap to zoom, drag to pan, and tap beside the image to close.
  • The full-screen dialog is named by `label`, and each thumbnail is a link to its image that still opens normally with Ctrl, Cmd or Shift.