# Product photo thumbnails and zoom that need a mouse
Source: https://easeweb.dev/learn/image-galleries
Topics: Complex widgets > Product photo galleries can be browsed and zoomed with a keyboard, and say which photo is shown (WCAG 2.1.1, 4.1.2)
The fix: Make each thumbnail a native button named by its image's alt text, and mark the current one with aria-current. Then give the keyboard a way to the detail: either a Zoom button over a box that scrolls, or a native dialog with the larger photo, or a link to the full-size photo.
Test with: keyboard, screen reader, forced colors
References: https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html https://www.w3.org/WAI/WCAG22/Techniques/failures/F54 https://www.w3.org/TR/wai-aria-1.2/#aria-current https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-current https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog
This is a recreated teaching example, not a finding about a named client. The code is a starting pattern: test it in your own product. No completed assistive-technology test is claimed here.
## What happens
A shop sells an enamel mug. Its product page has a large photo and three thumbnails under it: the front, the side and the back. The back carries small print that says "Dishwasher safe" and "350 ml", too small to read at this size. With a mouse it all works: click the last thumbnail and the back appears, move the mouse over it and it grows under the pointer until the print is easy to read.
Put the mouse aside and press Tab. Focus goes from wherever it was straight to Add to cart. The thumbnails are images with click handlers, which take no focus, so a keyboard user sees only the front of the mug. The zoom starts from the mouse moving over the photo, which the keyboard can't do, so even on the right photo the small print stays out of reach.
Some galleries get halfway: the thumbnails are real buttons, so Tab reaches them and Enter changes the photo. But their images have empty alt text, so each one reads as "button" and nothing else. The current one is marked by a border from a class, which a screen reader isn't told about, and pressing one changes the photo without a word. The zoom still needs the mouse.
## Why it fails
Success criterion 2.1.1 Keyboard asks that everything the mouse can do, the keyboard can do. Changing the photo is done by clicking an image, which takes no focus, so Tab never stops on it and Enter has nothing to press. The zoom listens for `mousemove`, which no key sets off. W3C's failure F54 describes this case: event handlers specific to a pointing device are the only way to run a function. Here the function is seeing the detail in the photo.
Success criterion 4.1.2 Name, Role, Value asks that controls expose a name, a role and their state. A clickable image has no button role. A button whose only content is an image with `alt=""` has a role and no name. And in both, the current thumbnail is known only from the `is-current` class that draws its border, a state that is never exposed. Turning the images into buttons fixes the keyboard and leaves this.
Pressing a thumbnail also changes the photo somewhere else on the page while focus stays on the thumbnail, so a screen reader user may not know that anything happened. Neither criterion requires that change to be announced. As good practice, the fixes below say it in a polite live region, as the carousels guide does for a new slide.
## Who is affected
The other photos often hold what the first one doesn't: the back, the label, the care instructions. Anyone who can't use a mouse meets only the front view, and may not learn that the rest exist.
## What automation and AI miss
Thumbnails built from images have no button role, so axe has nothing to check. The audit reports them when they are named as thumbnails in a class, show a pointer cursor, never take focus, sit near a much larger photo, and nothing else in the gallery can change it. That leaves out thumbnails beside previous and next buttons the keyboard can press, and FlexSlider's thumbnails, since, with one slider on the page, its default option changes the slide with the left and right keys anywhere on the page. When the thumbnails are buttons with no name, axe reports `button-name`, or `aria-command-name` for a div with `role="button"`.
Two things take a person, so the audit sends them as leads. One is a row of thumbnail buttons in which none carries a state: code can see that no `aria-current` is there, not what the page does instead. The other is a photo set up for a hover zoom (the marks left by Drift, elevateZoom, jQuery Zoom, Magento's magnifier and Dawn's hover setting), with no link round it and no control near it that says it zooms or opens the photo. A zoom written by hand leaves no such mark, and no check finds it.
Adding `tabindex="0"` to each image as a quick fix gives a Tab stop that Enter and Space do nothing on. A zoom made to start on focus is no better: the keyboard still can't move the view to the part of the photo it wants.
## Before: thumbnails and zoom that take only a mouse
```html
```
```css
.photo-frame { aspect-ratio: 1; overflow: hidden; }
.photo { display: block; width: 100%; }
.thumb { border: 2px solid transparent; cursor: pointer; }
/* The current thumbnail has a border, by a class only. */
.thumb.is-current { border-color: #2d3a55; }
```
```js
const frame = document.querySelector('.photo-frame');
const photo = frame.querySelector('.photo');
const thumbs = [...document.querySelectorAll('.thumb')];
thumbs.forEach((thumb) => thumb.addEventListener('click', () => {
photo.src = thumb.dataset.photo;
photo.alt = thumb.dataset.alt;
thumbs.forEach((other) => other.classList.toggle('is-current', other === thumb));
}));
// The zoom follows the mouse.
frame.addEventListener('mousemove', (event) => {
const box = frame.getBoundingClientRect();
const x = ((event.clientX - box.left) / box.width) * 100;
const y = ((event.clientY - box.top) / box.height) * 100;
photo.style.transformOrigin = `${x}% ${y}%`;
photo.style.transform = 'scale(3)';
});
frame.addEventListener('mouseleave', () => { photo.style.transform = ''; });
```
- The thumbnails are images that respond only to `click`, so they have no Tab stop and the keyboard can't show another photo.
- They have no role, and their alt text is empty.
- The current thumbnail is marked by the `is-current` class, which only draws its border.
- The zoom starts only from `mousemove`, so the keyboard can't reach the detail it shows.
- A new photo replaces the old one without a word to a screen reader.
## Before: thumbnail buttons that say nothing
```html
```
```css
.photo-frame { aspect-ratio: 1; overflow: hidden; }
.photo { display: block; width: 100%; }
.thumb { border: 2px solid transparent; cursor: pointer; }
/* The current thumbnail has a border, by a class only. */
.thumb.is-current { border-color: #2d3a55; }
```
```js
const frame = document.querySelector('.photo-frame');
const photo = frame.querySelector('.photo');
const thumbs = [...document.querySelectorAll('.thumb')];
thumbs.forEach((thumb) => thumb.addEventListener('click', () => {
photo.src = thumb.dataset.photo;
photo.alt = thumb.dataset.alt;
thumbs.forEach((other) => other.classList.toggle('is-current', other === thumb));
}));
// The zoom follows the mouse.
frame.addEventListener('mousemove', (event) => {
const box = frame.getBoundingClientRect();
const x = ((event.clientX - box.left) / box.width) * 100;
const y = ((event.clientY - box.top) / box.height) * 100;
photo.style.transformOrigin = `${x}% ${y}%`;
photo.style.transform = 'scale(3)';
});
frame.addEventListener('mouseleave', () => { photo.style.transform = ''; });
```
Tab now reaches every thumbnail, and Enter and Space press them, so the keyboard can show every photo. But the rest is no better:
- With `alt=""` on the only thing inside it, each button has no name, which fails 4.1.2.
- The current thumbnail is still marked only by `is-current`, so nothing tells a screen reader which photo is showing.
- The zoom still starts only from `mousemove`, which fails 2.1.1.
- A new photo replaces the old one without a word to a screen reader.
## After: a Zoom button over a box that scrolls
```html
Photo 1 of 3: Front of the mug
```
```css
.photo-frame { aspect-ratio: 1; overflow: hidden; }
.photo { display: block; width: 100%; }
.thumb { border: 2px solid transparent; cursor: pointer; }
/* The current thumbnail is drawn from the attribute a screen reader reads. */
.thumb[aria-current='true'] { border-color: #2d3a55; }
/* A contrast theme gives every border one system colour, so the current one takes another. */
@media (forced-colors: active) {
.thumb[aria-current='true'] { border-color: Highlight; }
}
/* Zoomed in, the browser scrolls the photo, and the arrow keys with it. */
.photo-frame.is-zoomed { overflow: auto; }
.photo-frame.is-zoomed .photo { width: 300%; max-width: none; }
```
```js
const frame = document.querySelector('.photo-frame');
const photo = frame.querySelector('.photo');
const thumbs = [...document.querySelectorAll('.thumb')];
const count = document.querySelector('.photo-count');
const zoom = document.querySelector('.zoom');
thumbs.forEach((thumb, i) => thumb.addEventListener('click', () => {
photo.src = thumb.dataset.photo;
photo.alt = thumb.querySelector('img').alt;
count.textContent = `Photo ${i + 1} of ${thumbs.length}: ${photo.alt}`;
thumbs.forEach((other) =>
other === thumb ? other.setAttribute('aria-current', 'true') : other.removeAttribute('aria-current'));
}));
// The zoom that follows the mouse stays, as a shortcut, until the photo is zoomed.
frame.addEventListener('mousemove', (event) => {
if (frame.classList.contains('is-zoomed')) return;
const box = frame.getBoundingClientRect();
const x = ((event.clientX - box.left) / box.width) * 100;
const y = ((event.clientY - box.top) / box.height) * 100;
photo.style.transformOrigin = `${x}% ${y}%`;
photo.style.transform = 'scale(3)';
});
frame.addEventListener('mouseleave', () => { photo.style.transform = ''; });
// The button grows the photo in the box, starting from its middle.
zoom.addEventListener('click', () => {
const zoomed = frame.classList.toggle('is-zoomed');
photo.style.transform = '';
if (zoomed) frame.tabIndex = 0;
else frame.removeAttribute('tabindex');
zoom.textContent = zoomed ? 'Zoom out' : 'Zoom in';
frame.scrollTo((frame.scrollWidth - frame.clientWidth) / 2, (frame.scrollHeight - frame.clientHeight) / 2);
});
```
1. Make each thumbnail a real button with its image inside. Tab reaches it and Enter and Space press it, with no key handling to write.
2. Write each thumbnail's alt text to say which photo it shows. With the image as the button's only content, that text is the button's name.
3. In the click handler, set `aria-current="true"` on the current thumbnail and take it off the others, so a screen reader says "current" on it.
4. Draw the border from `[aria-current='true']`, so the look and the announcement can't disagree.
5. As good practice, say which photo is shown in a polite live region, so a press is heard without moving focus.
6. Add a Zoom in button. It makes the photo three times as wide in a box that scrolls, and gives that box a Tab stop, so the arrow keys move around the photo. Keep the button ahead of the box, so Tab meets it first.
7. Leave the zoom that follows the mouse in place as a shortcut, and switch it off while the button has the photo zoomed.
This fixes both Befores and passes 2.1.1 and 4.1.2. The zoomed photo needs a large enough file behind it to keep its detail sharp at three times the width.
## After: the larger photo in a native dialog
```html
Photo 1 of 3: Front of the mug
```
```css
.photo-frame { aspect-ratio: 1; overflow: hidden; }
.photo { display: block; width: 100%; }
.thumb { border: 2px solid transparent; cursor: pointer; }
/* The current thumbnail is drawn from the attribute a screen reader reads. */
.thumb[aria-current='true'] { border-color: #2d3a55; }
/* A contrast theme gives every border one system colour, so the current one takes another. */
@media (forced-colors: active) {
.thumb[aria-current='true'] { border-color: Highlight; }
}
/* A photo wider than the box scrolls, and the arrow keys scroll it. */
.large-frame { max-width: 80vw; max-height: 70vh; overflow: auto; }
.large-frame img { display: block; }
```
```js
const frame = document.querySelector('.photo-frame');
const photo = frame.querySelector('.photo');
const thumbs = [...document.querySelectorAll('.thumb')];
const count = document.querySelector('.photo-count');
const dialog = document.querySelector('.large-view');
const large = dialog.querySelector('img');
thumbs.forEach((thumb, i) => thumb.addEventListener('click', () => {
photo.src = thumb.dataset.photo;
photo.alt = thumb.querySelector('img').alt;
photo.dataset.large = thumb.dataset.large;
count.textContent = `Photo ${i + 1} of ${thumbs.length}: ${photo.alt}`;
thumbs.forEach((other) =>
other === thumb ? other.setAttribute('aria-current', 'true') : other.removeAttribute('aria-current'));
}));
// The zoom that follows the mouse stays, as a shortcut.
frame.addEventListener('mousemove', (event) => {
const box = frame.getBoundingClientRect();
const x = ((event.clientX - box.left) / box.width) * 100;
const y = ((event.clientY - box.top) / box.height) * 100;
photo.style.transformOrigin = `${x}% ${y}%`;
photo.style.transform = 'scale(3)';
});
frame.addEventListener('mouseleave', () => { photo.style.transform = ''; });
// The button opens the large file. The dialog handles focus and Escape.
document.querySelector('.enlarge').addEventListener('click', () => {
large.src = photo.dataset.large;
large.alt = photo.alt;
dialog.showModal();
});
```
1. Make the thumbnails named buttons, with `aria-current` on the current one and its border drawn from it, as in the other fixes.
2. As good practice, say which photo is shown in a polite live region.
3. Add an Enlarge photo button that opens a `dialog` with `showModal()`. Focus moves in, the page behind becomes inert, Escape closes it, and focus goes back to the button.
4. Put the large photo in a box with a Tab stop, so the arrow keys move around it.
5. Leave the zoom that follows the mouse in place as a shortcut.
This fixes both Befores and passes 2.1.1 and 4.1.2. A lightbox library can take the dialog's place, for extras the native element leaves to you. Each must leave the dialog working from the keyboard:
- Swiping between photos: keep buttons for the previous and next photo, so a swipe is never the only way.
- Pinching to zoom: keep buttons for zooming, and a way to move around the photo with the keys.
- An opening animation: keep moving focus into the dialog, and back to the button when it closes.
The native `dialog` can be animated too, and takes any markup inside, including those buttons.
## After: a link to the full-size photo
```html
```
```css
.photo-frame { aspect-ratio: 1; overflow: hidden; }
.photo { display: block; width: 100%; }
.thumb { border: 2px solid transparent; cursor: pointer; }
/* The current thumbnail is drawn from the attribute a screen reader reads. */
.thumb[aria-current='true'] { border-color: #2d3a55; }
/* A contrast theme gives every border one system colour, so the current one takes another. */
@media (forced-colors: active) {
.thumb[aria-current='true'] { border-color: Highlight; }
}
```
```js
const frame = document.querySelector('.photo-frame');
const photo = frame.querySelector('.photo');
const thumbs = [...document.querySelectorAll('.thumb')];
const count = document.querySelector('.photo-count');
const link = document.querySelector('.full-size');
thumbs.forEach((thumb, i) => thumb.addEventListener('click', () => {
photo.src = thumb.dataset.photo;
photo.alt = thumb.querySelector('img').alt;
link.href = thumb.dataset.large;
count.textContent = `Photo ${i + 1} of ${thumbs.length}: ${photo.alt}`;
thumbs.forEach((other) =>
other === thumb ? other.setAttribute('aria-current', 'true') : other.removeAttribute('aria-current'));
}));
// The zoom that follows the mouse stays, as a shortcut.
frame.addEventListener('mousemove', (event) => {
const box = frame.getBoundingClientRect();
const x = ((event.clientX - box.left) / box.width) * 100;
const y = ((event.clientY - box.top) / box.height) * 100;
photo.style.transformOrigin = `${x}% ${y}%`;
photo.style.transform = 'scale(3)';
});
frame.addEventListener('mouseleave', () => { photo.style.transform = ''; });
```
1. Make the thumbnails named buttons, with `aria-current` on the current one and its border drawn from it, as in the other fixes.
2. As good practice, say which photo is shown in a polite live region.
3. Add a link to the full-size file, and point it at the current photo whenever a thumbnail is pressed. Tab reaches it, Enter opens the file in the browser, and Back returns to the page. Chromium and Firefox fit a large image to the window at first: the browser's zoom keys enlarge it, and once it is larger than the window, the arrow keys move around it.
4. Leave the zoom that follows the mouse in place as a shortcut.
This fixes both Befores and passes 2.1.1 and 4.1.2, as long as the file is large enough to show the detail. It is the smallest change here, and the link works before any script has run.
## Which option to use
Each one passes, and each keeps the hover zoom for people with a mouse. They differ in what the person sees when they ask for more. The Zoom button stays in place and takes the least room in the design, but the view is no larger than the photo's own box, which is small on a phone. The dialog gives the photo most of the screen, and is a usual form on product pages: WooCommerce, when a theme turns on its gallery zoom and lightbox, keeps a hover zoom and adds a control that opens the photo, and Shopify's Dawn theme opens the photo from a button by default. It costs a little more markup, and the rest of the page is out of reach until it closes. The link takes only a few lines and has little to break, and it takes the person away from the page. Choose it when there is no time for more, or as the fallback underneath a dialog, so the larger photo can still be reached if the script fails.
## Implementation decisions
`aria-current="true"` is the state for this, as it is for the current dot in a carousel: it marks one item in a set as the current one. `aria-pressed` would make each thumbnail a toggle, which suggests that a second press turns it off, and `aria-selected` isn't allowed on a button. Shopify's Dawn theme and Splide's navigation mode both use `aria-current` for a gallery's thumbnails.
A thumbnail can be named in other ways, such as `aria-label="Photo 3: back of the mug"` with the image's alt left empty. Alt text does the same job with less, and it is the words the live region reads.
A main photo that opens larger when a bare image is clicked fails 2.1.1 in the same way as the thumbnails. Put a button beside it, as the dialog fix does, or wrap the photo in a link to the large file, which is what PhotoSwipe asks for in its markup and what Fancybox's own example shows: a link can open the lightbox when the script has loaded, and the file when it hasn't. A lens over the photo can stay, since it needs no focus of its own.
The zoom's box needs a Tab stop only while it scrolls, so the fix adds `tabindex` when it zooms and takes it off again. A stop that does nothing at rest is one more for a keyboard user to pass.
When a gallery has many photos, the thumbnail row may itself scroll, with its own arrows. Those arrows are buttons with names too, and a thumbnail that takes focus while out of view has to scroll into it.
## Verify the fix
1. Put the mouse aside. Tab into the gallery: every thumbnail is a Tab stop, and Enter and Space show its photo.
2. Still without the mouse, use the fix's control to see the finest detail in the last photo, moving around it with the arrow keys, and get back to the page.
3. With a screen reader, Tab through the thumbnails. Each one says which photo it shows, and the current one says it is current. Press another: the state moves, and the new photo is named.
4. Turn on forced colors (Windows Contrast themes). The thumbnails, and which one is current, are still visible.
Record the OS, browser and assistive-technology versions, the build, the date, and the actual result of each step. Repeat after the gallery, its library or its theme changes.
## Limits
This is a starting pattern, not a guarantee for every application. It covers how the thumbnails and the zoom are reached and what the thumbnails say. A gallery built as slides with arrows and dots is covered in [carousels that keyboard and screen reader users can't use](/learn/carousels). A lightbox has its own needs for focus and closing: see [modals that leave keyboard focus behind them](/learn/modal-focus-management). A photo viewer that turns or zooms by dragging, pinching or tilting is in [pinch, drag and tilt gestures with no button](/learn/gestures). What each photo's alt text should say is a matter for the photo: this guide only asks that a thumbnail's alt text tells the photos apart, and that the large photo's stays in step when it changes.
## What the checkers report
- axe DevTools: "ARIA commands must have an accessible name"
- axe DevTools: "Buttons must have discernible text"
- Lighthouse: "`button`, `link`, and `menuitem` elements do not have accessible names."
- Lighthouse: "Buttons do not have an accessible name"
- WAVE: "Empty button"
## What screen readers do (tested by hand by EaseWeb)
`aria-current="page"`: Marks the link to the page you are on, in a menu, breadcrumbs or pagination.
| Screen reader | Browser and system | Tab to it | Down Arrow |
| --- | --- | --- | --- |
| JAWS | Chrome, Windows 11 | Not tested | Not tested |
| NVDA | Chrome, Windows 11 | Not tested | Not tested |
| JAWS | Edge, Windows 11 | Not tested | Not tested |
| NVDA | Firefox, Windows 11 | Not tested | Not tested |
| NVDA | Edge, Windows 11 | Not tested | Not tested |
| JAWS | Firefox, Windows 11 | Not tested | Not tested |
| VoiceOver | Safari, macOS | Not tested | Not tested |
| VoiceOver | Safari, iOS | Not tested | Not tested |
| TalkBack | Chrome, Android | Not tested | Not tested |
https://easeweb.dev/learn/screen-reader-support
---
Get this guide in your coding agent: MCP https://easeweb.dev/mcp (setup at https://easeweb.dev/services/developers)
