Skip to content

Fix: Navigation Overlay Close announces the author's own text - #82227

Open
Jiwoon-Kim wants to merge 2 commits into
WordPress:trunkfrom
Jiwoon-Kim:fix/overlay-close-aria-label
Open

Jiwoon-Kim wants to merge 2 commits into
WordPress:trunkfrom
Jiwoon-Kim:fix/overlay-close-aria-label

Conversation

@Jiwoon-Kim

Copy link
Copy Markdown
Contributor

What?

With Display Mode set to icon, the Navigation Overlay Close button is always
announced as "Close", whatever the author wrote in its text field.

$text = empty( $attributes['text'] ) ? __( 'Close' ) : $attributes['text'];
…
! $show_text ? 'aria-label="' . __( 'Close' ) . '"' : '',

The authored text is computed on the first line and the label ignores it.

Why?

icon is the default display mode, and it is the one mode where the label is the
button's entire accessible name — there is no visible text to fall back on. So an
author who writes "Dismiss menu" sees it in the text and both modes and loses
it in the mode where it matters most.

This looks like something left behind rather than a decision. When the block was
added, text was a rich-text attribute with "default": "Close", which made the
fixed label and the authored one the same string. text is now a plain string with
no default, and the label stopped following it.

The Search block already resolves the same situation the other way, naming its
icon-only button from the text the author gave it:

$button->set_attribute( 'aria-label', wp_strip_all_tags( $attributes['buttonText'] ) );

How?

The label uses the text that was already computed, with markup stripped, since an
attribute is not a place tags can live. The default is untouched: an author who has
written nothing still gets "Close".

The editor preview carried the same fixed string with the value it should use
already in scope, so it changes with it and the two stay in agreement.

Testing Instructions

  1. Add a Navigation block with an overlay, and select the Navigation Overlay Close
    block inside it.
  2. Set Display Mode to Text, and change the text to "Dismiss menu".
  3. Set Display Mode back to Icon.
  4. Inspect the button on the front end: aria-label="Dismiss menu".
  5. Clear the text and confirm the label falls back to "Close".
  6. In Text and Both modes there is no aria-label, because the visible text is
    already the button's name and a label would repeat it.

phpunit/blocks/render-block-navigation-overlay-close-test.php covers the four
cases: authored text in icon mode, the empty fallback, markup stripped from the
label, and no label when the text is visible.

OK (4 tests, 9 assertions)

Both changed files pass phpcs --standard=phpcs.xml.dist.

Screenshots or screencast

Rendered with displayMode: "icon" and text: "Dismiss menu":

<!-- before -->
<button type="button" aria-label="Close"><svg …/></button>

<!-- after -->
<button type="button" aria-label="Dismiss menu"><svg …/></button>

A note on scope

This is the accessibility half of one small thing, and I have deliberately not
touched the rest of it here.

While looking into it I noticed that Core spells "show an icon, text, or both" four
different ways across blocks that all render an action control:
displayMode: icon|text|both here, buttonUseIcon in Search, hasIcon + icon in
Navigation, and showIcon + iconPosition in Accordion — with the lightbox
controls having no attribute at all. Their supports differ too: this block has
color, spacing and typography but no border, dimensions or shadow, so a
theme cannot give an icon-only control a shape or a container size.

That is a larger conversation, and it overlaps with
#79057 on Button icons and
with the Icon Registry work in
#81225 /
#82062. I would rather raise it
separately than widen this fix, which stands on its own.

With the display mode set to icon, the button's label was always the
string "Close", whatever the author had written. Someone who labelled it
"Dismiss menu" got that wording on screen in the other modes and lost it
in this one -- the only mode where the label is the button's entire
accessible name, because there is nothing else to read.

The text was already computed one line above, with the same default
applied when the author has written none.

This looks like something left behind rather than intended: `text` used
to be a rich-text attribute defaulting to "Close", which made the fixed
label and the authored one the same string. It is now free text with no
default, and the label stopped following it.

The editor preview had the same fixed string, with the value it should
use already in scope, so it changes with it.

Markup is stripped from the label, since an attribute is not a place
tags can live, matching how the Search block names its own icon-only
button from its button text.
@github-actions github-actions Bot added [Package] Block library /packages/block-library First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository labels Aug 31, 2026
@github-actions

Copy link
Copy Markdown

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @Jiwoon-Kim! In case you missed it, we'd love to have you join us in our Slack community.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

@Jiwoon-Kim
Jiwoon-Kim marked this pull request as ready for review August 31, 2026 06:17
@github-actions

github-actions Bot commented Aug 31, 2026 •

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: Jiwoon-Kim <kimjiwoon@git.wordpress.org>
Co-authored-by: jorgefilipecosta <jorgefilipecosta@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

@github-actions

Copy link
Copy Markdown

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

  • Required label: Any label starting with [Type].
  • Labels found: [Package] Block library, First-time Contributor.

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.

@t-hamano t-hamano added [Type] Bug An existing feature does not function as intended [Focus] Accessibility (a11y) Changes that impact accessibility and need corresponding review (e.g. markup changes). [Feature] Navigation Overlays labels Sep 3, 2026

@jorgefilipecosta jorgefilipecosta left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The change looks good 👍

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Feature] Navigation Overlays First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository [Focus] Accessibility (a11y) Changes that impact accessibility and need corresponding review (e.g. markup changes). [Package] Block library /packages/block-library [Type] Bug An existing feature does not function as intended

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants