Lightbox and gallery
Pictures shown small, opened large. A set becomes a gallery to page through; a picture in an article opens by itself.
Show code
---
import MediaCarousel from '@somnia/core/components/MediaCarousel.astro';
import bay from '../assets/media/inspection-bay.jpg';
---
<MediaCarousel label="Shadowing at the depot" items={[
{ type: 'image', src: bay, alt: 'A bus over an inspection bay in a depot', title: 'The inspection bay', caption: 'Where a bus is checked from underneath.' },
// …
]} /> When to use it
- A set of photographs or films people will want to look at closely: a yacht, a project, a place.
- A picture in running text with detail too small to read at the column's width: a screen, a diagram, a plan.
Use something else when:
- The pictures are steps of one story, each with words: a carousel, or just the page.
- The picture is decoration. It doesn't need opening, so it isn't a button.
- The thing to show is a working page: embed it in a frame. Frames never open in the viewer.
Two ways in
- A gallery (
MediaCarousel, above): a grid of thumbnails, or thefeaturelayout of one large picture and four small, with "+N photos" on the last and a "View all N photos" button. Films sit in the same set and play in the video player. - Pictures in running text (
FigureViewer): every figure in a case study, an article or a brand guide page opens in the viewer. Figures side by side or in a gallery page together. Try one on a case study.
How it works
- The viewer is the browser's own
<dialog>: Escape closes it, the page behind can't be reached or scrolled, and the focus goes back to the picture that opened it. - Previous and Next buttons, the Left and Right arrow keys and, on touch screens, a sideways swipe. A swipe down closes it. It never moves by itself.
- "Image 2 of 4" under the picture, said to screen readers as it changes, and a strip of small pictures to jump to any one.
- A full-screen button, remembered for the browser tab; Escape leaves full screen first in the text viewer.
- Captions and alt text travel with the picture into the viewer.
- Thumbnails are cropped to 3:2 by default;
fit="contain"shows the whole picture on a white tile, for plans, diagrams and menus. grid=makes a viewer with no thumbnails of its own, opened by the page's buttons (data-mc-for): crew portraits in their cards, guests' photos under a review.- In print the thumbnails are printed and the viewer is not.
Do and don't
Do
- Write alt text for every picture: it is what the viewer says
- Give each a short title, and a caption where it adds something
- Blur faces, number plates and names before publishing
Don't
- Put words that matter only in a picture
- Open the viewer by itself, or page it on a timer
- Use a gallery for one picture: show it
Accessibility
What it does for you
- Each thumbnail is a button named by its title, saying it opens the viewer. A picture in running text becomes a button named "View larger image" and its alt text.
- The viewer is the browser’s own modal dialog, named by the gallery’s label: the focus stays inside, Escape closes, the page behind can’t be reached or scrolled.
- On closing, the focus goes back to the thumbnail or picture that opened it.
- Previous, Next and Close are named buttons; Full screen is one button that says whether it is on; the strip of small pictures is a group of buttons, each named for its picture, the one showing marked current.
- "Image 2 of 4" is said as the picture changes. Each picture keeps its alt text, title and caption in the viewer.
- It pages only when asked: buttons, arrow keys or a swipe. Never on a timer.
- The buttons’ focus ring has an inner ring, so it shows on a dark picture.
What you need to do
- Alt text for every picture. In the viewer it is all a screen reader user gets.
- A title for each item, and a
labelthat says what the set is. - Words that matter go in the caption or the page, not in the picture.
- A film in the set follows the video player’s rules.
Keyboard
| Key | What it does |
|---|---|
| Tab | Each thumbnail. In the viewer: full screen, Close, Previous, Next, then the strip. |
| Enter or Space | Opens the viewer at that picture. |
| Left and Right | The picture before, the picture after. They go round. |
| Escape | Closes the viewer. In the text viewer, it leaves full screen first. |
What a screen reader is told
- Each thumbnail: its title, "open in the viewer".
- The viewer by the gallery’s label, as a dialog.
- "Image 2 of 4" when the picture changes, and the picture by its alt text.
- Whether full screen is on.
This is what the browser reports to assistive technology. What each screen reader then says varies, and has not been listened to yet.
WCAG 2.2
| Criterion | Level | How this meets it |
|---|---|---|
| 1.1.1 Non-text Content | A | Alt text is carried into the viewer; a thumbnail in a titled grid is named by its title. |
| 2.1.1 Keyboard | A | Everything by keyboard: open, page, jump, full screen, close. |
| 2.1.2 No Keyboard Trap | A | Escape always leaves; the focus is kept in only while the viewer is open. |
| 2.4.3 Focus Order | A | The focus goes into the viewer on opening and back to its opener on closing. |
| 2.5.1 Pointer Gestures | A | Swipes have buttons that do the same. |
| 2.5.8 Target Size (Minimum) | AA | Viewer buttons 40px; strip buttons 60 by 42px. |
| 2.2.2 Pause, Stop, Hide | A | Nothing pages by itself. |
| 4.1.2 Name, Role, Value | A | The dialog and each control have a role and a name; the strip is a named group. |
| 4.1.3 Status Messages | AA | The counter is a polite live line. |
The criteria this component has a part in. A page that uses it still has to meet the rest.
Checked
| Check | How | Result |
|---|---|---|
| Automated (axe-core) | WCAG 2.0, 2.1 and 2.2 rules at A and AA, the page in light and in dark | Passed Nothing found, light or dark |
| Narrow screen | No sideways scrolling at 320px wide (WCAG 1.4.10) | Passed No sideways scrolling |
| Keyboard and what the browser reports | Real key presses on the live example, and the role, name and state given to assistive technology | Passed 15 of 15 checks pass |
| On paper | Somnia’s print check: no overlaps, stranded headings or controls on the page | Passed No faults on 6 sheets |
| Screen reader | Listened to by a person, in VoiceOver and NVDA | Not yet Not yet checked by a person |
The 15 checks made with the keyboard, on the example at the top of this page:
- Passed Tab reaches each thumbnail: a button named by its picture’s title, saying it opens the viewer
- Passed Enter opens the viewer at that picture: a modal dialog named for the gallery
- Passed Space opens it too
- Passed In the viewer Tab goes through Full screen, Close, Previous, Next and the strip, and never reaches the page behind
- Passed Right and Left page through and go round, and the counter says where
- Passed The strip is a group named "Choose an image"; each of its buttons is named for its picture and the one showing is current
- Passed Enter on a strip button shows that picture
- Passed Full screen is one button with one name that says whether it is on
- Passed Escape closes the viewer and the focus goes back to the thumbnail that opened it
- Passed A click on the dimmed page closes it
- Passed While it is open the page behind can’t take the focus and doesn’t scroll
- Passed The viewer’s buttons are 40px and their focus ring has an inner ring, to show on a dark picture
- Passed It never pages by itself: three seconds on, the same picture shows
- Passed In running text a picture is a button named "View larger image" and its alt text; Enter opens it, Escape closes it and the focus goes back
- Passed In the text viewer Escape leaves full screen first, and closes on the second press
Run by script on against Somnia DS 1.89.0, in Chromium with axe-core 4.14.0. How these checks work, and every component's results.
Not yet checked
- How it sounds in a screen reader (VoiceOver, NVDA, TalkBack) has not been checked by a person. The roles, names and states the browser reports are checked by script; what is actually spoken is not.
- Windows high contrast (forced colours) has not been looked at by a person.
- The text viewer (
FigureViewer) and the gallery (MediaCarousel) are two pieces of code that do the same job. The checks below run on the gallery’s example and on a case study’s pictures; they are not one component yet. - A picture in running text is an image given the role of a button. A real button round the image would be the plainer thing. Not changed.
- Pinch to zoom inside the viewer on a phone has not been tried on each browser.
Evidence
Where it's used
| Where | For |
|---|---|
| mediadreams.co.uk | Every picture in a case study, an article and the brand guide’s written pages. |
| Headland Yachting | Each yacht’s photographs and films (the feature layout), crew portraits in their cards, and guests’ photos under their reviews. |
| Staging sites | The Media library’s photos and videos. |
What we saw, and what changed
| When | What we saw | What changed |
|---|---|---|
| The page behind the viewer scrolled, and full screen blew upright pictures up past the screen. | The page stays put; upright pictures are kept whole (1.22.1). | |
| A feature gallery showed five pictures and nothing said there were more. | "+8 photos" on the last, and a "View all N photos" button (1.22.1). | |
| The arrows sat halfway down the viewer, not the picture, and the buttons’ focus ring vanished on a dark picture. | The arrows follow the picture, and the ring has an inner ring (1.32.0). | |
| On touch screens the viewer paged by its buttons only. | Swipe sideways to page and down to close, one finger, not on a film, not when zoomed in (1.32.0). | |
| Only case studies had a viewer for pictures in text. | It is a component; articles and brand guides get it too (1.63.0). | |
| The text viewer made a logo shown as an example into a button inside an image, which a screen reader can’t reach. | It leaves live examples, and pictures that are part of a named image, alone (1.80.0). | |
| Both viewers’ strips of small pictures had a name and no role, so the name was told to nobody. | Each is a group (1.88.0). | |
| Full screen changed its name and its pressed state together: "Exit full screen, pressed". | One name, and the pressed state says whether it is on (1.88.0). |
From building and using it on real sites, each entry taken from the changelog or the build's own notes. This is observation by the studio and its clients, not research sessions with users.
What it rests on
- ARIA Authoring Practices: Dialog (Modal): Focus moves into a dialog, stays there, and returns to what opened it; Escape closes it.
What we don't know yet
- How many people open a picture, or page past the first, is not counted.
- No user has been watched using either viewer.