The aria-hidden attribute: when to use it, and what to do when Tab reaches what it hides


A link that aria-hidden="true" hides from screen readers is still one Tab press away for someone using the keyboard. The attribute takes an element out of the accessibility tree, the version of the page that screen readers read, and leaves the screen and the keyboard alone. It's meant for a decorative icon. A closed panel that holds links needs hidden or inert, which keep the focus out too.
Hiding a panel without losing the focus
#What does aria-hidden="true" do?
The aria-hidden="true" attribute removes an element and everything inside it from the accessibility tree, the version of the page that the browser passes to screen readers. It keeps a screen reader from repeating what the page already says: an icon next to a word, or duplicated text like the 12" on a record store's product card. MDN, Mozilla's reference documentation, only allows it when assistive technologies get the same meaning and function some other way.
On the “Boots” page of Ridgeway Bootworks, our demo bootmaker, the “Shop the collection →” link hides its arrow this way. When we checked Chrome's accessibility tree, the link's name was just “Shop the collection”. Without the attribute, the arrow, a plain text character, would be part of the link's name.
Marker 1. The link's arrow, visible on screen. Marker 2. The link and its text in the accessibility tree, “Shop the collection”, with no arrow.That is all the attribute does: the element stays on screen, and its links and buttons stay within reach of Tab. MDN and Chrome's accessibility guide therefore rule it out on any element that can take focus, and on any element that contains one, since the attribute applies to everything inside. The other ways to hide content have their own glossary entry, hidden content.
On the same page, the side cart carries the attribute on the whole panel, which holds a close button and three links, “Check out” among them. That's the panel Lighthouse flags.
The aria-label attribute: when to use it and how to word it
#Why do Lighthouse and Chrome flag focusable elements inside aria-hidden?
Lighthouse and axe, the testing engine behind it, flag an aria-hidden area that the Tab key can still go into. Chrome's console warns when the focus lands there. A side panel that opens over the page should follow three rules:
- closed, it's out of the Tab order and out of the accessibility tree;
- open, Tab and Shift+Tab stay inside the panel;
- closed again, it gives the focus back to the button that opened it.
The notes that explain the WCAG criterion Focus Order illustrate the second rule with a modal dialog, which blocks the page behind it. Axe files its alert under another WCAG criterion, Name, Role, Value. In Europe, EN 301 549 repeats that criterion for web pages. It's the standard drafted as one voluntary way to meet the European Accessibility Act, Directive (EU) 2019/882.
#What happens to keyboard focus inside an aria-hidden area?
Keyboard focus walks into an aria-hidden area even when that area is off screen, like the demo's closed cart. The tab order runs into the cart after the last visible button: for four presses of Tab, someone using the keyboard can't see where the focus is.
The second “Add to cart”, the last visible control.
“Close cart”, inside the hidden cart: no focus ring on screen.
The first product link, invisible.
The second product link, invisible.
The “Check out” link, invisible; the next press leaves the page.
In Lighthouse, the page fails just one audit, on the cart's <aside>. The accessibility score only drops to 95: four presses lost off screen cost just five points. The audit's title reads “[aria-hidden="true"] elements contain focusable descendents”, misspelling and all. Behind it sits the axe rule aria-hidden-focus, which the axe DevTools extension also reports and rates “serious”.
When the cart opens, the script dims the page and puts aria-hidden="true" on its main content, <main>. From the “Cart (2)” button, Tab still goes through the four links and buttons of the dimmed page first. Axe no longer counts an error there: it sees an overlay covering the screen, assumes a modal dialog is open and lists <main> among the items to check by hand.
#What does “Blocked aria-hidden on an element” mean in Chrome's console?
Chrome writes this warning when an element that has the focus sits inside an aria-hidden="true" area. Lighthouse and axe catch the problem as soon as the page loads. The console reports it only when the focus gets there, here on the first Tab press into the demo's closed cart:
Blocked aria-hidden on an element because its descendant retained focus. The focus must not be hidden from assistive technology users. Avoid using aria-hidden on a focused element or its ancestor. Consider using the inert attribute instead, which will also prevent focus. For more details, see the aria-hidden section of the WAI-ARIA specification at https://w3c.github.io/aria/#aria-hidden.
Element with focus: <button.close#close>
Ancestor with aria-hidden: <aside.drawer#cart>From that first press, the whole cart is back in Chrome's accessibility tree: its heading, the focused button and the three links that Tab hasn't reached yet. That's what “Blocked” refers to: Chrome stopped honoring the aria-hidden of the entire panel, so screen readers get all of it back.
Marker 1. The cart back in the accessibility tree: the complementary region, its heading, the Close cart button, the list of two links and the Check out link. Marker 2. The Blocked aria-hidden warning in the console.
Shopify theme accessibility: what Shopify checked, and what's left to test
#What should replace aria-hidden: hidden, inert or dialog?
A panel that opens over the page is best rebuilt as a <dialog>. Opened with showModal(), it makes the rest of the page inert, out of reach of the keyboard, the mouse and screen readers. When a <dialog> won't work, hidden and inert take over, and aria-hidden stays reserved for content that never takes focus.
#How do you replace aria-hidden with a dialog?
Chrome's guide to the navigation drawer builds the side panel as a modal <dialog>, an element the major browsers have supported since March 2022. Rebuilt that way, our cart drops out of the tab order while it's closed. Once open, it puts the focus on “Close cart”, and Tab moves only through its four controls and the browser's own interface. When it's closed with its button or with Esc, the focus goes back to “Cart (2)”.
Marker 1. The dimmed page behind the cart, where Tab put the focus on “Add to cart”.Avoid
<button id="cart-button" type="button" aria-expanded="false">Cart (2)</button>
<main id="content">…</main>
<aside id="cart" class="drawer" aria-hidden="true">
<h2>Your cart</h2>
<button id="close" type="button">Close cart</button>
…
</aside>
<script>
const cartButton = document.querySelector("#cart-button");
const cart = document.querySelector("#cart");
cartButton.onclick = () => {
document.querySelector("#content").setAttribute("aria-hidden", "true");
cart.removeAttribute("aria-hidden");
cart.classList.add("open");
cartButton.setAttribute("aria-expanded", "true");
};
</script>Correct
<button id="cart-button" type="button" aria-expanded="false">Cart (2)</button>
<main id="content">…</main>
<dialog id="cart" class="drawer" aria-labelledby="cart-title">
<h2 id="cart-title">Your cart</h2>
<button id="close" type="button">Close cart</button>
…
</dialog>
<script>
const cartButton = document.querySelector("#cart-button");
const cart = document.querySelector("#cart");
cartButton.onclick = () => {
cart.showModal();
cartButton.setAttribute("aria-expanded", "true");
};
cart.querySelector("#close").onclick = () => cart.close();
cart.onclose = () => cartButton.setAttribute("aria-expanded", "false");
</script>The browser handles all of this on its own, with no focus script. That's why Chrome's guide to dialogs says not to add role="dialog", aria-modal, a script that keeps the focus inside or handles Esc, or any inert toggling.
#When should you use hidden or inert instead?
Chrome recommends inert when a <dialog> isn't an option. That happens with some frameworks, with layouts that clash with the way a dialog is positioned on top of everything, and with some overlays that don't block the page.
- Closed, the panel gets
hidden, which takes it off the screen, out of the accessibility tree and out of the Tab order, with no need foraria-hiddenon top. If it has to stay in the page so it can slide in,inerttakes it out of the Tab order, away from the mouse and out of the tree, as Chrome recommends. - Open and built by hand, the panel needs the rest of the page set to
inert, here<main>and the header: Tab then moves only through the cart. Nothing on screen shows that an area is inert, which is what the dimmed page is for.
When the panel closes, give the focus back to the “Cart (2)” button, as Chrome asks, then hide the panel. With aria-hidden, skipping that step leaves the focus on “Close cart”, hidden along with the panel. Before moving the focus, remove inert from the page, header included: on the demo, the button refused the focus while it was still inert.
function closeCart() {
document.querySelector("main").inert = false;
document.querySelector("header").inert = false; // "Cart (2)" can take the focus again
cartButton.focus(); // the focus goes back to this button
cartButton.setAttribute("aria-expanded", "false");
cart.hidden = true; // then the panel hides
}#How do you check that the fix holds?
Check with the Tab key first, because the panel's CSS can undo the fix. On our demo, the panel's display: flex won out over both hidden and the closed <dialog>, and Tab still went into the cart. With hidden, axe didn't catch it, since there was no aria-hidden left to test. One CSS rule for each closed state got rid of the cart for good:
/* Cart as a <dialog>: closed, it has no open attribute */
dialog.drawer:not([open]) { display: none; }
/* Cart hidden with the hidden attribute */
.drawer[hidden] { display: none; }On the fixed page, Tab stops at the seven visible controls while the cart is closed, and moves only through the cart once it's open. The console stays empty, axe reports nothing and Lighthouse climbs back to 100. The closed cart is gone from Chrome's accessibility tree, and across the whole page, aria-hidden="true" remains only on the decorative arrow of “Shop the collection”.
Google Lighthouse accessibility score: what a 100 counts, and what to test by hand
On a live site, the Includdy scan lists the aria-hidden areas where Tab reaches a link or a button. For each one, its guided fix puts the faulty HTML side by side with a component corrected by Includdy's AI, to review before it goes into the code.


