Repository navigation
Gallery block - Improve accessibility of lightbox controls #77545
Description
What problem does this address?
PR 62906 adds lightbox support for the Gallery block in WordPress 7.0).
The block offers three options for its navigation controls: "Icon," "Text," and "Both."
The Icon type is currently set as the default. When a user selects this, the Close, Previous, and Next buttons do not display a visible label on hover or keyboard focus.
An aria-label is present, so the current implementation technically meets WCAG 2.1 4.1.2 Name, Role, Value. However, it does not protect several user populations who rely on the visible interface:
- Users with cognitive disabilities, including dyslexia, ADHD, dyscalculia, memory impairments, and learning differences
- Older users, who are generally less fluent with modern UI iconography
- Low-vision users who do not use screen readers and whose visual parsing benefits from the redundancy of text over a single glyph
- Touch users, for whom hover states are not available
- First-time users of the interface, who have not yet built a mental model of the lightbox controls
For these users, icon-only navigation shifts cognitive load onto the user, requiring recall rather than recognition (Nielsen's Heuristic #6, one of the most empirically supported principles in HCI). Nielsen Norman Group's icon usability research shows that even well-recognized icons perform measurably better with text labels present.
This issue proposes two related improvements that address the gap at different layers.
What is your proposed solution?
Add a visible label on hover and focus-visible to icon-only controls**
Surface the existing aria-label text as a visible tooltip via a CSS ::after pseudo-element, triggered on :hover and :focus-visible. Illustrative example below:
.wp-lightbox-container button:hover::after,
.wp-lightbox-container button:focus-visible::after {
content: attr(aria-label);
position: absolute;
}
This adds no new information to the accessibility tree (screen readers already receive the aria-label), so role="tooltip", aria-describedby, and JavaScript are not required. The pattern automatically satisfies WCAG 2.5.3 Label in Name, because the visible text is pulled directly from the accessible name.
Update the default setting to "Both" instead of "Icon"
Change the default value of the label display setting so newly-inserted Gallery blocks display both icon and text labels out of the box.
Existing saved blocks would be unaffected; this change would only apply to newly-inserted blocks.
Activity
vishnupprajapat commentedon Apr 22, 2026
Hi! I'd like to take a look at this issue.
vishnupprajapat commentedon Apr 22, 2026
Since hover is not available on touch devices, should we also show labels on tap or keep "Both" as the recommended default for better mobile usability?
kedarjoyner commentedon Apr 22, 2026
@vishnupprajapat Great question. I agree on keeping "Both" as the recommended default, rather than showing labels on tap for touch devices.
Both Material Design's tooltip guidelines and Nielsen Norman Group's Tooltip Guidelines recommend that tooltips should not be used for information essential to completing a task. For Close, Previous, and Next, the label is essential for users to understand what each button will do before they act, and users can't tell whether a first tap activates the control or just reveals a label. A misread second tap on Close could dismiss the lightbox entirely.
From NNG:
Hope that makes sense!
vishnupprajapat commentedon Apr 27, 2026
Thanks for the detailed explanation, that makes sense!
Agree that relying on tooltips for essential actions isn’t ideal, especially on touch devices.
Keeping "Both" as the default seems like the most reliable and user-friendly approach.
I’ll keep this in mind while working on the implementation. Appreciate the clarification!
carolinan commentedon Apr 29, 2026
I think ideally, all paginations should be looked at and be updated to something more uniform.
What I mean is that there are many cases where one would want to navigate to next or previous:
Gallery lightbox
Comment pagination
Query pagination
Next and previous post (single post)
Slider (coming soon)
And they are now all handled individually, with different settings, different icons, and even different ways to add the texts.
For example, there are two different chevrons used...
@WordPress/gutenberg-design thoughts?
vishnupprajapat commentedon Apr 30, 2026
That’s a really good point.
Having multiple pagination/navigation patterns across different areas (gallery lightbox, comments, next/previous posts, etc.) can definitely lead to inconsistency and a fragmented user experience.
A more unified approach could help here. For example:
At the same time, we may still need slight variations depending on context (e.g. lightbox vs post navigation), but aligning the core patterns would make the overall experience more cohesive.
Curious if there are any existing design guidelines or plans to unify these patterns across Gutenberg.
jasmussen commentedon May 13, 2026
This is one of those careful deliberations that, at the scale of a project the size of WordPress, gets magnified to a billion use cases. My instinct for handling such things in general, is to empower users to create exactly what they wish, what meets their criteria and own instincts. Through it all, there still needs to be a default; a sort of good defaults, else options mantra.
In this case, I find myself echoing Carolina, that this default was chosen specifically because it is a reproducible interface that appears in more than just one place with those same rules. It is not perfect, that's one of the reasons for adding options, and top of my own wishlist is to actually give visual feedback on mobile devices so when you page between images in a carousel, the image actually moves under your thumb, as opposed to now where the thumbswipe is simply a gesture. More than any on-press text label, this is an intuitive function on a mobile device.
t-hamano commentedon May 13, 2026
Thank you for your suggestion.
Personally, I feel that making "Both" the default is excessive. In my experience, this chevron icon is widely used as a "move" context, and I believe it sufficiently conveys its intent even without a label. This is similar to how the default for the toggle buttons in the Navigation block is an icon.
In my opinion, this issue could perhaps be closed as "maybe later".
@joedolson Please let me know if you have any thoughts.
joedolson commentedon May 14, 2026
In my opinion, the role of WordPress as a content authoring tool is to ensure that the interfaces we create meet a fundamental level of accessibility (defined for the project as WCAG 2.2 at Level AA). As it currently exists, the defaults meet that standard, and have options that enable the user to choose an enhanced level of accessibility.
I don't think it's necessary to change the defaults at the block level, but I do think it should be possible to alter the defaults at the theme level or on a global level. If you are aiming to meet a higher level of accessibility, you should not need to make that choice every time you implement a block - it should be a style choice for "how this block works on our site".
As far as I know,
theme.jsondoes not currently allow theme authors to configure lightbox options globally, which I think would be a more useful way to manage this issue.Speaking personally, yes - of course I would prefer to see the default option to use text labels. It is unquestionably the more accessible choice. I am aware however, that we need to operate on a balance that keeps friction lower, and would rather see us spend time adding more enhanced controls via theme.json. If this option could be controlled via theme.json, I'd feel more comfortable making changes to the defaults, as that barrier becomes lower.
t-hamano commentedon May 16, 2026
This might be a larger undertaking, but I agree with this approach.
kedarjoyner commentedon Jun 4, 2026
I guess I'm not sure why we wouldn't start with the highest level of accessibility if we know it's ultimately the best option? And then, people can choose lesser options, but it seems we could set the highest standards on the web.
@joedolson
Thanks for laying this out! This framing is helpful, especially the distinction between meeting the project’s baseline accessibility standard and allowing themes to opt into a higher standard through
theme.json.I definitely understand the concern about balancing accessibility with friction. At the same time, defaults carry a lot of weight because many users will never revisit these settings or understand that there is an accessibility tradeoff being made. If text labels provide a clearer and more accessible experience, I wonder whether that should be the baseline Core experience, with themes or users able to opt into a more minimal interface if that better fits their needs.
I also agree that
theme.jsoncontrol would be valuable. I see that as especially important for institutions and theme authors who need to maintain consistent accessibility standards across many sites.As a possible middle ground, I wonder if the icon-only lightbox controls could expose a visible label on :hover and :focus-visible? Our accessibility partners found this issue when testing, which was one of the impetuses for submitting this issue. This would keep the default interface visually minimal, but still provide a visible text label when a user is interacting with the control.
This is a great discussion and helps me learn a whole lot, thank you!