aria-hidden on body or html: what it breaks

What aria-hidden does

aria-hidden="true" removes an element and everything inside it from the accessibility tree. The element stays on screen and stays in the tab order. It stops existing only for a screen reader.

That is the right tool for a decorative icon next to a text label. On <body> or <html> it asks for the whole document to be ignored. Browsers differ in how far they honor that, and some refuse it outright on those two elements, but the markup is wrong either way and no page should depend on which browser is reading it.

What squirrel checks

One check, aria-hidden-body, at severity error and weight 10, the highest in the category.

• Fail when <html> or <body> carries aria-hidden="true". The message names the culprit: Document <html> element is aria-hidden, or Document <body> is aria-hidden. The finding carries the issue Page content is inaccessible to assistive technology and the fix Remove aria-hidden from body/html element.
• Pass with Document body is not hidden from assistive technology.

The value comparison is exact, so aria-hidden="True" is not reported even though it has the same effect in some browsers.

How to fix it

<body>
  <div id="app">...</div>
  <div role="dialog" aria-modal="true">...</div>
</body>

Remove the attribute. The usual reason it got there is a modal library trying to hide the page behind an open dialog. Use aria-modal="true" on the dialog, or apply aria-hidden to the dialog’s siblings, never to an ancestor of the dialog itself.

Enable / disable

Disable this rule

[rules]
disable = ["a11y/aria-hidden-body"]

Disable all Accessibility rules

[rules]
disable = ["a11y/*"]

Enable only this rule

[rules]
enable = ["a11y/aria-hidden-body"]

enable replaces the default ["*"], so this is the only rule selected. Leave disable out: a rule that matches any disable pattern is skipped even when enable names it. Only an enabled setting under a rule’s own [rule_options] table overrides both lists.

Related rules

• a11y/aria-hidden-focus: hidden regions that still contain tabbable elements.
• a11y/aria-dialog-name: the modal that usually causes this.
• a11y/aria-allowed-attr: other ARIA attributes that contradict what the element is.
• content/hidden-text: content hidden visually rather than from assistive technology.

Accessibility findings ship in every audit next to the SEO, performance and agent experience rules. See Website security scan with AI for how an agent works through a report.

References

• aria-hidden, MDN
• WAI-ARIA 1.2, W3C

Check your site

Run squirrel audit https://example.com and open the Accessibility section of the report. This one is either present or it is not, so a single finding covers the page. Signed-out local audits need no account and cost nothing. Signed-in audits spend credits.