Add zoomable images feature by GuillaumeGomez · Pull Request #3127 · rust-lang/mdBook

GuillaumeGomez · 2026-05-26T16:14:23Z

Fixes #2075.

The "zoomed-in" image looks like this:

The JS is only used to "zoom out" images with the "escape key", otherwise the feature works entirely without JS.

It works as follows: there is a (hidden) checkbox right before the image. The image itself is inside the label associated to the checkbox, meaning that when you click on the image, you switch the value of the checkbox. And thanks to :checked CSS selector, it changes the display of the zoomed out image.

To make it obvious that you can "zoom in"/"zoom out" on an image, I changed the cursor to look like a loop using the CSS cursor: zoom-in|zoom-out property.

I also realized that images had the alt attribute, but not the title one, so I added it while I was at it.

GuillaumeGomez · 2026-05-26T17:06:24Z

Updated failing tests as well, ready for review. :)

GuillaumeGomez · 2026-06-08T16:13:10Z

ping @ehuss

ehuss · 2026-06-08T16:15:35Z

Won't this break images that are links?

GuillaumeGomez · 2026-06-08T16:22:19Z

I think it would yes. Didn't think about that. If I only allow to zoom on non-link images, does it sound good to you?

shenef · 2026-06-08T17:47:59Z

The description mentions the escape key for zooming back out, how would that work on a mobile device? Or does tapping it again toggle off the invisible checkbox?
I have a case where i currently use an image with a link to open a separate full-size version of the image. (740x638 -> 3712x3200)
So with this feature there would be no more need to do that.

GuillaumeGomez · 2026-06-08T17:56:41Z

The description mentions the escape key for zooming back out, how would that work on a mobile device? Or does tapping it again toggle off the invisible checkbox?

Tapping again will zoom-out.

rustbot · 2026-06-08T19:29:33Z

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

GuillaumeGomez · 2026-06-08T19:47:27Z

@ehuss Disabled the feature on images inside links and extended test to check it as well.

ehuss

Thanks!

I'm not going to block on it, but this doesn't seem to support the ability to trigger with the keyboard. Generally we try to ensure to follow accessibility guidelines as much as we can.

Just curious, was it intentional that you can still scroll when the image is zoomed in? (I'm not sure if I have a preference, just checking.)

I'm slightly uneasy not having a way to turn this off. I'm fine with starting without it, but if people have issues, we may need to add something. In particular, small images like icons probably don't need or want to be zoomed in this way.

View changes since this review

ehuss · 2026-06-19T15:18:57Z

+
+                    let mut label = Element::new("label");
+                    label.insert_attr("class", "checkbox-label".to_tendril());
+                    label.insert_attr("for", img_input_id.to_tendril());


The IDs end up getting broken on the print page because it rebuilds the IDs to be unique. I think the "for" here ends up being the wrong value in that case.

I'm not sure how to fix that, other than the print page also handling this attribute.

It's the print page, so I don't think it matters in this case, no?

ehuss · 2026-06-19T15:20:09Z

+                } else {
+                    img.insert_attr("title", alt.into());


Why was this fallback to add the alt as the title added?

I mentioned it in my first comment:

I also realized that images had the alt attribute, but not the title one, so I added it while I was at it.

It's better for accessibility, and for other users, to have text when they hover an image without moving for a while.

ehuss · 2026-06-20T21:00:36Z

+                    label.insert_attr("for", img_input_id.to_tendril());
+                    self.push(Node::Element(label));
+
+                    self.append(Node::Element(img.clone()));


I'm a little concerned about this approach of using a duplicated <img> tag. Screen readers may have difficulty handling this. I think at a minimum it should have aria-hidden="true". I'm a bit uncomfortable with this approach in general, though I'm willing to give it a try.

I think screen readers all handle display: none, so I think we're fine (although if we could test it, would be even better). However, won't aria-hidden=true be an issue when the image is zoomed-in?

ehuss · 2026-06-20T21:05:56Z

+
+                    self.append(Node::Element(img));
+
+                    // We exit the `label` and the `div`.


This comment seems off. There is no div AFAIK.

Perhaps it means:

Suggested change

// We exit the `label` and the `div`.

// We exit the `label` and the `span` (which used push_no_stack).

ehuss · 2026-06-20T21:21:52Z

    margin-right: 8px;
 }
+
+.content .checkbox-img, .checkbox-label > .img-wrapper {


Can you add comments explaining what these rules are for and what they do? It can be just a short comment on each selector to explain what it's for (image zoom) and what that selector is doing.

ehuss · 2026-06-20T21:29:52Z


 (function chapterNavigation() {
+    function zoomOutImages() {
+        for (const elem of Array.from(document.querySelectorAll('input.checkbox-img'))) {


I believe this can be simplified:

Suggested change

for (const elem of Array.from(document.querySelectorAll('input.checkbox-img'))) {

for (const elem of document.querySelectorAll('input.checkbox-img')) {

It can, but since we make modifications to the DOM, there is a non-zero chance that the selector list will recompute itself between each items (that was a huge issue in older rustdoc when we used it to generate [-] buttons).

ehuss · 2026-06-20T21:36:42Z

+call-function: ("check-image-zoomed-in", {})
+
+// We click on the wrapper to "zoom out".
+click: ".checkbox-label > img"


Is it intentional that this clicks on the image underneath the wrapper? That is, should this be something like ".image-wrapper > img" or ".image-wrapper" to simulate what the user would actually click on?

Well, they click on the image, but the image being part of the label, since there is no preventDefault() on the image, the event is propagated to the parent until the parent is the label which then handles the click event and stops its propagation. So it is how users will interact with it.

ehuss · 2026-06-20T21:39:45Z

    }

+    /// Returns the current `img_label_id` and increase its value.
+    fn get_current_img_label_id(&mut self) -> usize {


Just a very minor nit, but this method name seemed a little confusing to me since it has a side effect. Perhaps something like get_next_img_label_id would be a little clearer?

ehuss · 2026-06-20T21:46:14Z

Also, it's probably a good idea to include at least some note in the documentation that this exists. Perhaps on the Images section?

GuillaumeGomez · 2026-06-22T13:39:07Z

I'm not going to block on it, but this doesn't seem to support the ability to trigger with the keyboard. Generally we try to ensure to follow accessibility guidelines as much as we can.

I was sure I tested that, I'll double-check and add a regression test to ensure it works.

Just curious, was it intentional that you can still scroll when the image is zoomed in? (I'm not sure if I have a preference, just checking.)

I didn't consider it an issue but I can do it if you want as even with JS (it's required for that as I need to change a parent's style, so cannot be done with only CSS).

I'm slightly uneasy not having a way to turn this off. I'm fine with starting without it, but if people have issues, we may need to add something. In particular, small images like icons probably don't need or want to be zoomed in this way.

I can add a CLI option for that if you want? As for small images, if I want to know their size, I would need another dependency for that. Not sure it's worth it but again, your call.

GuillaumeGomez · 2026-06-22T16:35:59Z

I simplified the DOM generation: no need for an ID anymore. We can now make the zoom in feature work with the keyboard (still no JS, works with spacebar). Added a GUI test for it as well. And mentioned it in the mdbook guide.

I didn't add a new CLI option to disable it yet. Waiting for you to confirm if you want it or not.

GuillaumeGomez · 2026-06-22T19:26:15Z

Updated tests with HTML comparisons. :)

GuillaumeGomez requested a review from ehuss May 26, 2026 16:14

GuillaumeGomez mentioned this pull request May 26, 2026

Zoomable Images #2075

Open

GuillaumeGomez force-pushed the zoom-in branch 2 times, most recently from e172cff to 4d67425 Compare May 26, 2026 16:19

rustbot added the S-waiting-on-review Status: waiting on a review label May 26, 2026

GuillaumeGomez added 4 commits June 8, 2026 19:57

Add "zoom-in" feature on images

23d6071

Add title attribute on images

86191a7

Add regression test for the "zoom-in" feature

4e224f8

Add possibility to "zoom out" using the escape key

6f5720b

GuillaumeGomez force-pushed the zoom-in branch from 4d67425 to 3615043 Compare June 8, 2026 19:29

GuillaumeGomez force-pushed the zoom-in branch from 3615043 to bb61242 Compare June 8, 2026 19:30

Only enable "zoom-in" feature on images not inside links

83f42f9

GuillaumeGomez force-pushed the zoom-in branch from bb61242 to 83f42f9 Compare June 8, 2026 19:40

ehuss reviewed Jun 20, 2026

View reviewed changes

GuillaumeGomez force-pushed the zoom-in branch from ae1f95b to 1c226f2 Compare June 22, 2026 16:35

GuillaumeGomez mentioned this pull request Jun 22, 2026

Fix weird layout bug with images in links #3142

Open

GuillaumeGomez force-pushed the zoom-in branch from 1c226f2 to 17d0639 Compare June 22, 2026 16:42

Make the "zoom in" feature work with keyboard and simplify DOM

337d692

Mention zoom-in feature in mdbook guide

03dd19a

GuillaumeGomez force-pushed the zoom-in branch from 17d0639 to 03dd19a Compare June 23, 2026 16:13


		self.append(Node::Element(img));

		// We exit the `label` and the `div`.

	// We exit the `label` and the `div`.
	// We exit the `label` and the `span` (which used push_no_stack).

	for (const elem of Array.from(document.querySelectorAll('input.checkbox-img'))) {
	for (const elem of document.querySelectorAll('input.checkbox-img')) {

Uh oh!

Conversation

GuillaumeGomez commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

GuillaumeGomez commented May 26, 2026

Uh oh!

GuillaumeGomez commented Jun 8, 2026

Uh oh!

ehuss commented Jun 8, 2026

Uh oh!

GuillaumeGomez commented Jun 8, 2026

Uh oh!

shenef commented Jun 8, 2026

Uh oh!

GuillaumeGomez commented Jun 8, 2026

Uh oh!

rustbot commented Jun 8, 2026

Uh oh!

GuillaumeGomez commented Jun 8, 2026

Uh oh!

ehuss left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GuillaumeGomez Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ehuss commented Jun 20, 2026

Uh oh!

GuillaumeGomez commented Jun 22, 2026

Uh oh!

GuillaumeGomez commented Jun 22, 2026

Uh oh!

GuillaumeGomez commented Jun 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

GuillaumeGomez commented May 26, 2026 •

edited

Loading

ehuss left a comment •

edited by rustbot

Loading

GuillaumeGomez Jun 22, 2026 •

edited

Loading