# Product photo zoom that needs a mouse

Source: https://easeweb.dev/learn/hover-zoom
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: Keep the zoom that follows the mouse as a shortcut, and add a way in that Tab reaches: either a Zoom in button that enlarges the photo in a box the arrow keys scroll, or a button that opens the larger photo in a native dialog, or a link to the full-size photo.
Test with: keyboard, speech input, forced colors
References: https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html https://www.w3.org/WAI/WCAG22/Techniques/failures/F54 https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex https://github.com/imgix/drift https://www.jacklmoore.com/zoom/

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, thumbnails of the front, the side and the back under it, and an Add to cart button. The back carries small print that says "Dishwasher safe" and "350 ml", too small to read at the photo's size. With a mouse it is easy: move the pointer over the photo and it grows to three times its size around the pointer, until the print can be read.

The thumbnails are buttons with names, so a keyboard user can Tab to the back and press Enter, and the back of the mug appears. Then they press Tab again, to find a way to enlarge it. Focus goes from the thumbnails straight to Add to cart. Nothing on the photo takes focus, and no key makes it grow, so the small print stays a grey smudge.

This is how the common zoom libraries work out of the box. Drift describes itself as "zoom on hover", and jQuery Zoom starts on `mouseover` unless told otherwise. Drift's own example sets it on a plain image, with nothing else to press, and a page built that way has no other way to see the photo larger.

## Why it fails

Success criterion 2.1.1 Keyboard asks that everything the mouse can do, the keyboard can do. Here the mouse can enlarge the photo and move around it. The zoom listens for `mousemove`, which no key sets off, and there is no button, link or Tab stop that does the same. W3C's failure F54 describes this case: event handlers specific to a pointing device are the only way to run a function. The function is seeing the detail in the photo.

A zoom made to start on focus is not enough. Even if Tab could reach the photo and enlarge it, the zoom follows the pointer: with no pointer, the keyboard has no way to move the view to the corner it wants to read.

## Who is affected

The detail is often what a buyer needs: the capacity, whether it goes in the dishwasher, the weave of a fabric, a size chart printed on a label. A person who can't use a mouse can choose every photo and still not read any of it.

## What automation and AI miss

The audit can't press a key and watch a photo grow. What it can see is the mark a zoom library leaves: the attributes and elements that Drift, elevateZoom, jQuery Zoom, Magento's magnifier and Shopify's Dawn theme, with its zoom set to Click and hover, add. When a photo carries one, sits in no link, and nothing near it that Tab reaches says it zooms, enlarges or opens the photo, the audit sends a lead, `ew:hover-zoom-manual-check`, for a person to check. A zoom written by hand, like the one in this example, leaves no such mark, and no check finds it.

A lead is not a finding: a page may offer the same detail in a way the audit doesn't know, such as a separate photo of the label. And no lead is not a pass: a button nearby whose words say "Zoom" stops the lead even if it opens something else. axe has nothing to check here: the photo is an image with alt text, and that passes.

## Before: a zoom that follows the mouse

```html
<div class="gallery">
  <div class="photo-frame">
    <img class="photo" src="mug-front.jpg" alt="Front of the mug">
  </div>
  <div class="thumbs">…</div>
</div>
```

```css
.photo-frame { aspect-ratio: 1; overflow: hidden; }
.photo { display: block; width: 100%; }
```

```js
const frame = document.querySelector('.photo-frame');
const photo = frame.querySelector('.photo');
// 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 zoom starts only from `mousemove`, and leaves on `mouseleave`. No key sets off either.
- Nothing in the gallery takes focus for the zoom: no button, no link, and the frame has no Tab stop.
- So the keyboard can change the photo but never see its detail.

## After: a Zoom button over a box that scrolls

```html
<div class="gallery">
  <button type="button" class="zoom">Zoom in</button>
  <div class="photo-frame" role="region" aria-label="Zoomed photo">
    <img class="photo" src="mug-front.jpg" alt="Front of the mug">
  </div>
  <div class="thumbs">…</div>
</div>
```

```css
.photo-frame { aspect-ratio: 1; overflow: hidden; }
.photo { display: block; width: 100%; }
/* 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 zoom = document.querySelector('.zoom');
// 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. Add a Zoom in button over the photo, ahead of it in the page, so Tab meets it first.
2. When it is pressed, make the photo three times as wide inside a frame that scrolls, and start from the middle of the photo.
3. Give the frame a Tab stop while it is zoomed, and a role and a name, so Tab reaches it, a screen reader can say what it is, and the arrow keys move around the photo. Take the Tab stop off again when it zooms out.
4. Change the button's words to Zoom out while the photo is zoomed, so it says what the next press does.
5. 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 the Before and passes 2.1.1. 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
<div class="gallery">
  <button type="button" class="enlarge">Enlarge photo</button>
  <div class="photo-frame">
    <img class="photo" src="mug-front.jpg" alt="Front of the mug">
  </div>
  <div class="thumbs">…</div>
  <dialog class="large-view" aria-label="Enlarged photo">
    <form method="dialog">
      <button>Close</button>
    </form>
    <div class="large-frame" tabindex="0" role="region" aria-label="Large photo">
      <img src="" alt="">
    </div>
  </dialog>
</div>
```

```css
.photo-frame { aspect-ratio: 1; overflow: hidden; }
.photo { display: block; width: 100%; }
/* 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 dialog = document.querySelector('.large-view');
const large = dialog.querySelector('img');
// 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 photo at its full size. The dialog handles focus and Escape.
document.querySelector('.enlarge').addEventListener('click', () => {
  large.src = photo.currentSrc;
  large.alt = photo.alt;
  dialog.showModal();
});
```

1. Add an Enlarge photo button over the photo, ahead of it in the page.
2. When it is pressed, put the photo that is showing, with its alt text, into a `dialog`, and open it with `showModal()`. Focus moves in, the page behind becomes inert, Escape or the Close button closes it, and focus goes back to the button.
3. Show the photo at its own size in a box with a Tab stop, a role and a name, so the arrow keys move around it.
4. Leave the zoom that follows the mouse in place as a shortcut.

This fixes the Before and passes 2.1.1. 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
<div class="gallery">
  <div class="photo-frame">
    <img class="photo" src="mug-front.jpg" alt="Front of the mug">
  </div>
  <div class="thumbs">…</div>
  <a class="full-size" href="mug-front.jpg">Open full-size photo</a>
</div>
```

```css
.photo-frame { aspect-ratio: 1; overflow: hidden; }
.photo { display: block; width: 100%; }
```

```js
const frame = document.querySelector('.photo-frame');
const photo = frame.querySelector('.photo');
const link = document.querySelector('.full-size');
// 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 link follows the photo whenever it changes.
photo.addEventListener('load', () => { link.href = photo.currentSrc; });
```

1. Add a link to the photo's file under the gallery. Tab reaches it, Enter opens the file in the browser, and Back returns to the page.
2. Point the link at the new file whenever the photo changes, so it always opens the photo on show.
3. Leave the zoom that follows the mouse in place as a shortcut.

Browsers fit a large image file to the window at first. Firefox's zoom keys then enlarge it, and once it is larger than the window, the arrow keys move around it; in other browsers, try how far the keyboard alone can enlarge it. This fixes the Before and passes 2.1.1 only while the browser lets the keyboard enlarge the file, and 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 keeps the hover zoom for people with a mouse. The Zoom button and the dialog pass in any browser; the link passes only where the browser lets the keyboard enlarge the file it opens. 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 both its gallery zoom and its lightbox, keeps the 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, but it takes the person away from the page and leaves the enlarging to the browser. WooCommerce's gallery has one under its hover zoom: each photo sits in a link to its full-size file. 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

The zoom's frame needs a Tab stop only while it scrolls, so the first 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.

A page that serves smaller files to small screens with `srcset` shows a smaller file in `currentSrc`. Point the dialog and the link at the largest file instead, kept in a data attribute beside `src` and changed with it, as Drift does with `data-zoom`.

A main photo that opens larger when the bare image is clicked fails 2.1.1 in the same way as the hover zoom. 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 drawn over the photo can stay, since it needs no focus of its own.

On a touch screen there is no hover. Drift starts its zoom from a touch by default, and WooCommerce switches jQuery Zoom to a tap on touch screens, so the zoom often still works there; the fixes' controls work on a touch screen too, and don't depend on the library's choice.

Adding `tabindex="0"` to the photo and starting the zoom on focus gives a Tab stop that shows one fixed part of the photo, with no way to move to the rest.

## Verify the fix

1. Put the mouse aside. Tab through the gallery: a control that zooms, enlarges or opens the photo is a Tab stop, its focus ring shows, and Enter presses it.
2. Show the photo with the finest detail and use that control. With the arrow keys alone, move around the enlarged photo until the detail can be read.
3. Get back to the page with Zoom out, Escape or Back, and Tab on from where you were.
4. With voice control, say "Click" and the control's visible words. It is pressed.
5. Turn on forced colors (Windows Contrast themes). The control, and the focus ring on the enlarged photo, can still be seen.

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 keyboard reaches the detail a hover zoom shows. The thumbnails that change the photo are in [product photo thumbnails that need a mouse or say nothing](/learn/image-galleries). 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). The browser's own zoom and a screen magnifier enlarge the photo as drawn on the page; they are the person's tools, and this guide is about the zoom the page adds.

---

Get this guide in your coding agent: MCP https://easeweb.dev/mcp (setup at https://easeweb.dev/services/developers)
