Image block: Add "Mark as decorative" toggle for accessibility

[SteveJonesDev]

What?

Adds a "Mark as decorative" toggle to the Image block's Content inspector panel. When enabled, the image is flagged as purely decorative for assistive technologies.

Related: #66491

Why?

Images that are purely decorative (e.g. dividers, flourishes, or redundant visuals that add no informational value) should be hidden from screen readers. Currently the Image block has no first-class way to do this — users who know to leave the alt text empty get a vague "Leave empty if decorative" hint, but there is no explicit control and the intent is not saved in the block data. This PR makes the decorative intent explicit and machine-readable.

How?

• Adds an isDecorative boolean attribute to block.json.
• Adds a checkbox ("Mark as decorative") to the Content tab of the block inspector, under "Media", alongside the alt text field.
• When enabled:
  • The checkbox is hidden when the lightbox is enabled, since a decorative image should not expand in a lightbox. Enabling the lightbox also resets isDecorative to false.
  • If the image has existing alt text, a caption, or a link, a confirmation dialog is shown warning that those values will be removed.
  • The alt text field is cleared and hidden.
  • The caption is not rendered.
  • The link toolbar button is hidden.
  • role="none" is added to the element in both the saved HTML (save.js) and the server-side render (index.php).
  • The editor preview updates its internal alt attribute to "This image has been marked as decorative; its file name is " (or without the filename if unavailable) so screen reader users in the editor have meaningful context.
• Selecting a new image resets isDecorative so the flag does not carry over unintentionally.

Testing Instructions

Open a post or page in the block editor.

1. Insert an Image block and upload or select an image.
2. Open the Settings sidebar and go to the Content tab.
3. Under Media, verify a "Mark as decorative" checkbox is visible below the alt text field.
4. With no alt text, caption, or link set, check the checkbox — confirm it enables immediately with no confirmation dialog.
5. Uncheck it, add alt text, then re-check — confirm a confirmation dialog appears listing what will be removed. Confirm, and verify the alt text field is hidden.
6. Verify the caption is no longer visible while the checkbox is checked.
7. Verify the link toolbar button is no longer visible while the checkbox is checked.
8. Save/publish the post and view the frontend — inspect the <img> element and confirm it has role="none".
9. Return to the editor, replace the image via the toolbar, and confirm the checkbox resets to off on the new image.
10. Enable the Lightbox on the image and confirm the "Mark as decorative" checkbox is no longer visible. Re-disable the lightbox and confirm the checkbox reappears.
11. With "Mark as decorative" checked, enable the lightbox — confirm isDecorative is reset and the checkbox is hidden.

Testing Instructions for Keyboard

1. Tab to the Image block and open the Settings sidebar.
2. Navigate to the Content tab using the keyboard.
3. Tab to the "Mark as decorative" checkbox and activate it with Space.
4. If a confirmation dialog appears, confirm it is focus-trapped and can be confirmed or cancelled with the keyboard.
5. Confirm the alt text field is no longer present and the caption/link toolbar buttons are no longer reachable.

Screenshots or screencast

Use of AI Tools

This PR was developed with assistance from Claude Code (Anthropic). All generated code has been reviewed and tested by the author and a second human code reviewer.

[github-actions]

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: SteveJonesDev <[email protected]>
Co-authored-by: t-hamano <[email protected]>
Co-authored-by: jameskoster <[email protected]>
Co-authored-by: joedolson <[email protected]>
Co-authored-by: jasmussen <[email protected]>

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

[github-actions]

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @SteveJonesDev! 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.

[joedolson]

There are a couple additional things that I'd like to see this be able to do:

If the image is decorative:

1. disable the caption control or remove the decorative status if a caption is added
2. disable the link control or remove the decorative status if a link is added

[SteveJonesDev]

Thanks @joedolson for the feedback! I've implemented both of these. I went with disabling the controls rather than auto-removing the decorative status. A linked or captioned image isn't truly decorative by definition, so keeping them mutually exclusive felt like the right call.

I also added a confirmation dialog that appears when enabling the toggle if the image already has alt text, a caption, or a link, since clearing those is a destructive action the user should opt into explicitly.

[t-hamano]

Thanks for the PR! Overall, it looks good, but design feedback will likely be needed.

There are two things I noticed.

---

The caption can be entered unintentionally. Please take the following action:

• Inset an Image block
• Enter a caption
• Enable "Mark as decorative"
• Click "Mark as decorative"
• The caption will be empty, but you can enter the caption again.

Recording.2026-05-12.000901.mp4

---

Both "Mark as decorative" and Lightbox can be enabled. Please take the following action:

• Enable "Enlarge on click"
• Enable "Mark as decorative"
• The link setting toolbar button disappears, but the lightbox is internally enabled.

Recording.2026-05-12.001435.mp4

In my opinion, "Mark as decorative" should be hidden when a lightbox is applied to the image.

[SteveJonesDev]

Thanks for the review, @t-hamano! I've applied all your suggestions. I also fixed a bug where the caption field remained editable for a moment after marking an image as decorative, it was staying visible while the block was still selected instead of hiding immediately. And I've added logic so the "Mark as decorative" toggle is hidden when the lightbox is enabled, since the two options are mutually exclusive. Enabling the lightbox also clears the decorative flag so it doesn't silently persist in the saved data.

[jameskoster]

A potentially silly question: Does this need to be an option in the UI... couldn't we apply the logic automatically? IE if the user supplies no alt text, caption, etc, then the image is inherently decorative and we can update the markup accordingly. That way we sidestep the UX tension between this new option an all the existing ones, which is going to be tricky to get right.

[SteveJonesDev]

@jameskoster, Not a silly question at all. The issue is that an empty alt field is ambiguous. It could mean "this image is decorative" or "the author forgot to add alt text," and those are very different from an accessibility perspective. Right now WordPress can’t tell the difference.

An explicit toggle makes that intent clear and machine-readable, which helps accessibility audits, site reviews, and tooling distinguish intentional omission from missing alt text.

Automatically treating empty alt text as decorative would also be risky. If someone forgets to add alt text to a meaningful image, it could silently get role="none" and disappear from screen readers entirely. That’s probably worse than the current behavior.

Happy to work through UX concerns to get the experience right, but I don’t think they’re a reason to avoid having an explicit control.

[jasmussen]

I was going to ask the same question Jay did, glad it was answered. In that light, some thoughts:

• A checkbox feels more appropriate than a toggle control, since there is no visual feedback (lightswitch metaphor) in the canvas.
• I like that the alt text field gets disabled if toggled. Do we need a confirm? You can always undo, yes? Mostly worried with confirm dialogs creeping in where we don't absolutely need them, they can be quite intrusive and are most useful if an action is truly destructive.
• With the new checkbox, we can reduce the textarea help text to: "Describe the purpose of the image."

The help text for the checkbox/toggle feels a bit verbose, I wonder if there's a rephrase we can do to keep the same meaning but be more concise; remember this is something you will see for every single Image block you select. We need the meaning to be there, but with the textarea already linking out to external documentation, we can maybe be simpler here. An experiment; before:

[x] Mark as decorative
Enable if this image is purely decorative and should be ignored by assistive technologies.

After:

[x] Mark as decorative
Signal for this to be ignored by assistive technologies.

Perhaps slightly too short, but I intentionally omitted "image", as I could imagine this very checkbox appearing in other blocks eventually, i.e. could "Cover" benefit from it? And if yes, the checkbox needs to be identical across so that it is recognised as the same feature. If the above is too compressed, we could maybe add a generic term such as "Signal for this element", or something. We could even go simpler, a la:

[x] Mark as decorative
Ignore by assistive technologies.

Not quite sure I'm getting it right, but hopefully the intent comes through: the feature makes sense, now how do we make it as simple to understand and glanceable as possible?

[SteveJonesDev]

@jasmussen, Thanks for the thorough feedback!

Checkbox: agreed and already switched.

Confirm dialog: just to clarify how this works: the dialog only appears if the image actually has alt text, a caption, or a link that would be lost. If none of those are set, checking the box takes effect immediately with no interruption. So it should only ever surface when there's a genuine risk of data loss.

Alt text help: reduced to just "Describe the purpose of the image.", and I removed "Leave empty if decorative." since the checkbox makes that implicit.

Checkbox help text: landed on "Hidden from assistive technologies.", state description rather than an instruction, no mention of "image" so it works generically across blocks, and as concise as it can get while still being meaningful.

[jasmussen]

Confirm dialog: just to clarify how this works: the dialog only appears if the image actually has alt text, a caption, or a link that would be lost. If none of those are set, checking the box takes effect immediately with no interruption. So it should only ever surface when there's a genuine risk of data loss.

Indeed, but even if there's alt text, it's not really data loss since you have undo and even revisions. I personally favor to avoid the interruption of a confirm dialog with all that entails. But it is not strongly felt, if you feel this is necessary, go for it.

Nice instinct on the conditional! Good stuff.

[t-hamano]

Another issue we need to address is when the dataform-driven inspector fields are enabled. Enable the "Block fields" setting in the Gutenberg Experiments page.

The 'Mark a decorative' checkbox is missing. Additionally, when it is checked, the three fields Link, Caption, and Alt text need to be hidden.

[joedolson]

Regarding data loss: it's true that there's no real data loss. However, especially in a multi-editor environment, if one editor adds alternative text and a later editor decides an image is decorative, it's good to alert them to this. Otherwise, this could overwrite previous work. And while technically the data is not lost, that's only true for the admin - users will lose access to it immediately, and that could be significant.

I'm in favor of notifying users if a change they make is going to result in previous work no longer being visible on the front-end when that is not the sole intended result of the action (e.g., deleting content.)

[SteveJonesDev]

I was initial in favor of the confirmation but with the introduction of the dataform requirement a few things pushed me to remove it.

The dataform path makes it technically problematic. When the Gutenberg Experiments setting "Block fields: Show dataform driven inspector fields on blocks that support them" is enabled, the inspector is driven by a DataForm where field updates are synchronous data transforms, not React components. There's no render context to show a modal from, so a confirmation there would require a fully custom Edit component to manage its own dialog state, effectively reimplementing the same feature from scratch in a different architecture. Implementing a confirmation only in the standard inspector path would create an inconsistency between the two modes for the same action, which feels worse than having no confirmation at all. Solving it properly in both paths would be a significant scope increase and potentially not feasible within this PR.

The revisions diff captures all the attribute changes, so the history is fully auditable, and undo is available for the immediate case.

There are other equally destructive actions in the editor that don't currently follow the proposed confirmation pattern making this inconsistent with how the editor already behaves.

[joedolson]

If it's that much extra work, it's certainly not worth it. And yes, there are other destructive paths that are similar - e.g., changing the number of columns in a columns block, that can have equally destructive consequences. Although I can't offhand think of an example that has equivalently non-obvious consequences - e.g., noticing that a link has been removed could be quite subtle, where noticing that a column of content has been removed is pretty obvious.

[SteveJonesDev]

Fair point and I agree. The technical hurdles to achieve this in both paths are the blocker for me. Is it a common practice in Gutenberg to have parity between the two paths? I'd imagine this isn't the first time an issue like this has come up in regards to the dataform form path.

[jasmussen]

A note, this PR is a solid step forward and worth landing for that reason. If we find the data-loss issue emerges as problematic, it is likely problematic for adjacent dataform related pieces as well, and so a more generic solution across those items could be explored. As noted I've not strong feelings, so I'm not advocating in one direction or other, but mostly noting that this PR could be a win to ship even if followups could become necessary.

[t-hamano]

LGTM!

I tested whether role="none" would really be effective on CodePen, and indeed, VoiceOver seems to appropriately ignore the image.

Screen.Recording.0008-05-18.at.17.59.06.mov

[talldan]

Thanks for taking block fields into account when implementing this 👏

I noticed #66491 is still open, should this PR have closed it?