Skip to content

Patterns

Images and the lightbox

A content image on any Skribly page opens large in a dialog. A reader can zoom into a screenshot, move through a group of them and get back to the page exactly where they were. The same look comes from one React component and one small script.

Which one to useLink to the section Which one to use

  • A plain page or an Astro site. Do nothing: the site kit script enhances every content image in main by itself.
  • A React app. Use Lightbox and keep the open state and the index yourself.

In a site: nothing to writeLink to the section In a site: nothing to write

PageLayout includes the script. It turns an image in main into a button that opens the dialog, with the alt text in its name.

  • Figures that share one parent open as a group.
  • data-sk-lightbox-group on any element groups the images inside it.
  • data-sk-full on an image names a larger file than the one shown.

The script leaves these alone, and so does the attribute below:

  • images inside a link or a button, since they already do something;
  • decorative images with an empty alt, and the header, footer and navigation;
  • anything inside, or marked with, data-sk-lightbox="off".
Markup

The first image opens in the lightbox; the second one does not.

html
<figure>
  <img src="/shots/editor.webp" alt="The editor with a draft open" />
  <figcaption>The editor</figcaption>
</figure>

<img src="/logo-wall.webp" alt="Logos" data-sk-lightbox="off" />

In ReactLink to the section In React

Lightbox
tsx
<Lightbox images={images} index={index} onIndexChange={setIndex} isOpen={open} onOpenChange={setOpen} labels={labels} />

Every word is a label, including the position and the names of the thumbnails, so the app keeps its own language files.

ControlsLink to the section Controls

What a reader does, how, and what follows
ActionHowNote
CloseClose button, Escape, a click on the backdropFocus returns to the image that was opened
ZoomPlus and minus buttons, + and - keys, the wheel, a pinch, a double click or double tapZero or the reset button returns to the whole picture
PanDrag, or the arrow keys, while zoomed inThe picture cannot leave the screen
Previous and nextArrow buttons, the left and right arrow keys, a swipe on a phoneHome and End go to the first and last picture
JumpThe thumbnail row at the bottomThe current thumbnail is marked with aria-current

Writing the alt textLink to the section Writing the alt text

The picture is what the reader sees

alt="The editor with a draft open and the outline on the left"
Do. Say what the picture shows. The dialog repeats it as its name for the picture.
alt="screenshot"
Don’t. A word that names the file type tells nothing, and a caption cannot replace it.

AccessibilityLink to the section Accessibility

  • A modal dialog with a name; focus starts on Close, stays inside and returns to the image.
  • Every control is a button with a name, and the zoom and arrows work from the keyboard.
  • The position is announced politely when it changes.
  • The dialog uses the theme tokens, so it is right in the three themes and in forced colours.
  • With reduced motion, the fade and the zoom animation drop out.

Built to WCAG 2.2 AA as a target.

Search this site

Arrows move through the results, Enter opens one, Esc closes. Ctrl K /