---
title: accessible image modals
image:
  src: 2026/snacking-seagull.jpg
  alt: Image unrelated to post. A seagull floating in the water with a starfish hanging out of eir mouth.
tags:
  - reference
  - software
---

Recently I've been working on a single-page digital rendition of a zine complete with many hand-drawn images. The author wanted to be able to bring images up to a full-screen view, to either zoom in or to put the whole enlarged image on one screen with no scrolling. It was a real struggle to find resources on how to do this in an accessible manner, so I'm writing up what I did.

> Fair warning: This solution is likely imperfect.

## the `dialog` element

do you know how many tutorials want you to roll your own modals? It's a not-insignificant amount. W3Schools, top of the search results in many cases, recommends it in two places - [image modals](https://www.w3schools.com/howto/howto_css_modal_images.asp){target="_blank" rel="external"} and [responsive image modals](https://www.w3schools.com/css/css3_images_modal.asp){target="_blank" rel="external"}. Several search results for "image modal" pop up div solutions - [div modal 1](https://stackoverflow.com/questions/75598914/how-to-display-an-image-clicking-on-it-using-modal-window-on-html-css-and-js){target="_blank" rel="external"}, [div modal 2](https://dev.to/salehmubashar/create-an-image-modal-with-javascript-2lf3){target="_blank" rel="external"}, [div modal 3](https://www.youtube.com/watch?v=Y9TNHynFjaQ){target="_blank" rel="external"}.

If you don't know of the existence of `<dialog>`, a search for image modals will not get you there quickly.

If you search for *accessible* image modals, you'll still hear about `<div>`s. Hell, [W3C's ARIA Authoring Practices Guide uses a `<div>`](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/dialog/){target="_blank" rel="external"}. You kinda have to go digging to read about the [dialog element from Scott O'Hara](https://www.scottohara.me/blog/2023/01/26/use-the-dialog-element.html){target="_blank" rel="external"} or find [AccessibleWeb.dev's piece on modals](https://accessibleweb.dev/modals){target="_blank" rel="external"}. Or you can go [straight for Adrian Roselli](https://adrianroselli.com/2025/06/where-to-put-focus-when-opening-a-modal-dialog.html){target="_blank" rel="external"} and find examples that use the native `<dialog>` element. Thanks Adrian!

Did I roll my own modal at first? Regretfully, yes. I'd used the `<dialog>` element before... several years ago... in a project I don't have access to anymore... Needless to say, I had forgotten about its existence.

Anyway, I got there. Eventually. So let's talk about modals and `<dialog>`.

### what does `<dialog>` give us?

so, what do we get from the `<dialog>` element that we don't get from a `<div>` modal?

1. a semantically meaningful element
1. a backdrop that fills the screen behind the modal, styleable with `::backdrop`
1. automatic use of the `Esc` key to close the modal
1. automatic focus trapping that prevents any tabbing within the page behind the modal (users can tab off the page into the browser buttons)
1. the JS functions `.showModal()` and `.close()`
1. if `closedby` is set to `any`, clicking outside the modal (anywhere on the backdrop) will also close the modal
1. automatic return of focus to the element that triggered the modal
1. the `autofocus` attribute for in-modal elements to set which element should receive focus on opening the modal
1. the `open` attribute which is set on the `<dialog>` when open and removed when closed (when you use the functions mentioned previously)

and more. This is just the pieces in use for me. There's also things like [setting forms so that submission closes the dialog](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog#additional_notes){target="_blank" rel="external"} (point 1 in that list).

### what doesn't it give us?

1. a close button - gotta roll your own and attach the requisite `.close()` call (or rely on users hitting escape or clicking the backdrop)
1. prevention of scroll on the rest of the page

### a bug

MDN warns:

> Do not add the `tabindex` property to the `<dialog>` element as it is not interactive and does not receive focus.

— [`<dialog>`: additional notes](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog#additional_notes){target="_blank" rel="external"} (point 3 in that list).

despite this, I found that in Firefox (but not Edge), the *`<dialog>` itself was focusable*. I have no idea why, but I tested this on a totally unstyled and unmodified page and still found it to be true. As a focusable element, it made no sense. It had no interactivity and could not be activated.

I'm still torn: do I add `tabindex="-1"`? MDN specifically says not to, but I'm pretty sure they're warning against making it *focusable*. Why warn against making it nonfocusable when *it's not supposed to be focusable in the first place*, after all?

At current, I'm ambivalent, but I've added `tabindex="-1"` to handle Firefox's poor behavior. Making the dialog focusable is unhelpful and confusing.

## in addition to the `<dialog>`

here's what else I wrote...

### html

besides the `<dialog>`, I gave my `<img>` elements `tabindex="0"` to make them focusable.

### js

in `modal.js`, I created an `openDialog()` function that takes in the clicked image. It:

- creates a new `<img>` element and copies over the `src` and `alt` attributes - importantly, it doesn't copy the full `<img>` because we *don't* want to copy that `tabindex` attribute
- replaces the current `<img>` in the modal with our new copy with `replaceChild()` (or if there's no current one, it just appends)
- calls `dialog.showModal()`

I gave my close button two event listeners, one that listens for click events and one that listens for a keydown of the space or enter keys. In the case of the keydown, it calls `event.preventDefault()` to stop the space key from scrolling the underlying page.

I also looped through all images and attached my `openDialog()` function to any image with a `tabindex` attribute (I had some images that weren't intended to be fullscreened, so they lacked `tabindex`). Again, I gave them listeners on both click and keydown.

### css

here's the most relevant parts of the CSS:

- `dialog::backdrop` was given a [relatively calculated](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Colors/Using_relative_colors){target="_blank" rel="external"} color - `rgba(from var(--color-bg) r g b / .8)` - as well as a blur
- `body:has(dialog[open])` has `overflow: hidden` set
- `dialog img` uses a `max-height` as well as `object-fit: contain`

## errors? questions?

reach out!
