img-alt-decorative
Excluded <img>/<canvas>/<svg> must be decorative (manual review)
Flags <img>, <canvas> and <svg> elements excluded from the accessibility tree (aria-hidden, role="none"/"presentation", empty alt, or an unlabeled svg/canvas) for human review that they are purely decorative.
Applies to. Applies to visible <img>, <canvas> or <svg> elements excluded from the accessibility tree by any of: an aria-hidden ancestor-or-self, an explicit role="none"/"presentation" not overridden by focusability, an <img alt=""> (the native decorative marker, same focusability override; only a literally empty alt, so alt=" " is not one), an unlabeled <svg> whose implicit role is graphics-document (no img/graphics-symbol role restatement, aria-name, direct child <title>/<desc> with text wherever it is among the children, or focusability), or an unlabeled <canvas> with no explicit role at all. An element is skipped when an ancestor whose name stands for its content has an author-supplied name (aria-label, aria-labelledby, title, or an associated <label>): that name replaces what the image would have said (the common case: an icon-only button named with aria-label). Such an ancestor has a role named from its content (link, button, heading, cell, option, tab, treeitem, menuitem...) or with presentational children (img, slider, progressbar...). ACT e88epe skips the element under any ancestor named from author; this rule still asks under a named landmark, figure, group, region, dialog or composite widget (listbox, menu, grid...), whose name labels a container and says nothing of what an image in it shows: <figure aria-label="Photo: DR"> credits a photo. A link or button named by its text does not exempt an image beside the text either: a file-type, external-link or rating icon can say what the text does not, and ACT keeps it applicable. An element in an [inert] subtree, or behind an open modal dialog, is left out as other hidden content is, as img-alt-present leaves it out: it takes no interaction and no assistive technology gets it.
Expectation. Human review is required to confirm the excluded element is purely decorative and conveys no information a user would otherwise miss.
What a finding reports.
element:img,svgorcanvas.sameImageCount: how many of this result's findings show the same image, this one included: an <img> with the same current source (currentSrc, elsesrc), or an inline <svg> with the same root attributes that change its rendering (viewBox, width, height, class, style, fill, stroke, color) and the same markup. 1 for a canvas, an image with no source or markup to compare, or a lazy-loaded <img> whosedata:placeholder stands in for adata-srcordata-srcset.sameImageFirst: true on the first of them in document order, so a reader can review one copy and count the rest.reasonCode:IMAGE_ONLY_CONTROL_CONTENTwhen the image is the only content of a link or button (no text and no other image in it): the control then has no name from it, whether or not it decorates, withcontrolContentnaming the control's role (linkorbutton).EXCLUDED_ELEMENT_REVIEWotherwise.
These data.details fields help to read and reproduce a finding. Apart from reasonCode and the few fields Output schema names as stable, they are not a stable contract: a field may be renamed or dropped in a minor release, so don’t build on them.
Examples
<img src="quarterly-trend.png" alt="">
Marked decorative with alt="", but a filename like "quarterly-trend" suggests this might actually be an informative chart, not decoration.
<button aria-label="Close"><img src="x-icon.png" alt=""></button>
The button's own aria-label already provides the accessible name; the icon's exclusion isn't this element's decorative question to review.
How to check
When this rule can’t decide, it reports cantTell and leaves the question to a person. Each question it can ask is listed here under its reason code, with the steps to answer it. A finding carries the same steps as howToCheck, in the scan’s language. See Output schema.
EXCLUDED_ELEMENT_REVIEW
- Find the image, svg or canvas the report names and look at it on the page.
- Ask what a user would miss if it were removed: information, a label, a chart's data, or nothing.
- If it conveys something, check whether nearby visible text already says the same thing.
Pass. The image is purely decorative (a spacer, divider, ornament or a picture whose content the text already gives), so hiding it loses nothing.
Fail. The image conveys information that nothing else on the page gives, yet it is hidden from assistive technology, which fails WCAG 1.1.1.
IMAGE_ONLY_CONTROL_CONTENT
- Find the link or button the report names; its only content is a hidden image.
- Read the control's computed name in the Accessibility pane, or move to it with a screen reader and listen.
- Compare what is announced with what the control does.
Pass. The control is still announced with a name that says what it does.
Fail. The control is announced with no name, or only its address, because its sole image is hidden, which fails WCAG 1.1.1 (F89).