Skip to content

Ignore alt check for aria-hidden images #1851

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
coliff merged 3 commits into from
Apr 17, 2026
+40 −4
Merged

Ignore alt check for aria-hidden images #1851

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2663e9e
Ignore alt check for aria-hidden images
coliff Apr 16, 2026
4d64844
Handle trimmed aria-hidden for <img> alt rule
coliff Apr 16, 2026
db67e8e
Test aria-hidden behavior in alt rule
coliff Apr 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions dist/core/rules/alt-require.js
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 5 additions & 1 deletion src/core/rules/alt-require.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,11 @@ export default {
const col = event.col + tagName.length + 1
let selector

if (tagName === 'img' && !('alt' in mapAttrs)) {
if (
tagName === 'img' &&
!('alt' in mapAttrs) &&
mapAttrs['aria-hidden']?.trim().toLowerCase() !== 'true'
) {
reporter.warn(
'An alt attribute must be present on <img> elements.',
event.line,
Expand Down
28 changes: 28 additions & 0 deletions test/rules/alt-require.spec.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,34 @@ describe(`Rules: ${ruleId}`, () => {
expect(messages.length).toBe(0)
})

it('Img tag with aria-hidden="true" and no alt attribute should not result in an error', () => {
const code = '<img width="200" height="300" aria-hidden="true">'
const messages = HTMLHint.verify(code, ruleOptions)
expect(messages.length).toBe(0)
})

it('Img tag with aria-hidden="TRUE" and no alt attribute should not result in an error', () => {
const code = '<img width="200" height="300" aria-hidden="TRUE">'
const messages = HTMLHint.verify(code, ruleOptions)
expect(messages.length).toBe(0)
})
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot Apr 16, 2026

Choose a reason for hiding this comment

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

medium

It would be beneficial to add test cases for aria-hidden="false" (to ensure it still warns when alt is missing) and for values with whitespace (e.g., "true ") to verify the robustness of the implementation.

Suggested change
})
})
it('Img tag with aria-hidden="false" and no alt attribute should result in an error', () => {
const code = '<img width="200" height="300" aria-hidden="false">'
const messages = HTMLHint.verify(code, ruleOptions)
expect(messages.length).toBe(1)
})
it('Img tag with aria-hidden="true " and no alt attribute should not result in an error', () => {
const code = '<img width="200" height="300" aria-hidden="true ">'
const messages = HTMLHint.verify(code, ruleOptions)
expect(messages.length).toBe(0)
})


Comment thread
coliff marked this conversation as resolved.
it('Img tag with aria-hidden=" true " and no alt attribute should not result in an error', () => {
const code = '<img width="200" height="300" aria-hidden=" true ">'
const messages = HTMLHint.verify(code, ruleOptions)
expect(messages.length).toBe(0)
})

it('Img tag with aria-hidden="false" and no alt attribute should result in an error', () => {
const code = '<img width="200" height="300" aria-hidden="false">'
const messages = HTMLHint.verify(code, ruleOptions)
expect(messages.length).toBe(1)
expect(messages[0].rule.id).toBe(ruleId)
expect(messages[0].line).toBe(1)
expect(messages[0].col).toBe(5)
expect(messages[0].type).toBe('warning')
})

it('Img tag have not alt attribute should result in an error', () => {
const code = '<img width="200" height="300">'
const messages = HTMLHint.verify(code, ruleOptions)
Expand Down
3 changes: 2 additions & 1 deletion website/src/content/docs/rules/alt-require.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ keywords:

import { Badge } from '@astrojs/starlight/components';

Alt of `img` must be present and alt of `area[href]` and `input[type=image]` must be set with a value.
Alt of `img` must be present unless the image is hidden from assistive technologies with `aria-hidden="true"`. Alt of `area[href]` and `input[type=image]` must be set with a value.

Level: <Badge text="Warning" variant="caution" />

Expand All @@ -23,6 +23,7 @@ Level: <Badge text="Warning" variant="caution" />

```html
<img src="test.png" alt="test" />
<img src="decorative.png" aria-hidden="true" />
<input type="image" alt="test" />
Comment thread
coliff marked this conversation as resolved.
<area shape="circle" coords="180,139,14" href="test.html" alt="test" />
```
Expand Down
Loading