accessibility · web-platform
aria-hidden
also called aria-hidden="true" (aria), hidden from assistive technology (community)
An attribute that removes an element and its whole subtree from the accessibility tree while leaving it visible on screen.
aria-hidden="true" is the exact inverse of visually hidden. One takes
an element out of the picture and leaves it in the accessibility
tree; this one leaves the pixels exactly where they are and deletes
the node. That is the right tool for anything on screen that carries no information: the
glyph inside an icon button whose label is already written in text, an ornament between a
headline and a byline, a duplicated copy of a quotation, a decorative overlay of grain or
scanlines. The reader loses nothing, because there was nothing there to lose.
It takes the whole subtree with it, and that is what separates it from the two attributes
it gets confused with. Presentation role strips one element of its
own semantics and leaves every child in place, so a table used for layout stops announcing
rows while its cells keep being read. A decorative image with an empty
alt drops one image. aria-hidden cuts a branch: the element, its children, and their
children, with no way to mark a descendant present again from inside. Point it at a
container and everything in that container is gone.
The first trap is the reason the attribute has a warning printed next to it in every
reference. Hiding the node does nothing to focusability, so aria-hidden on anything
focusable, or on any ancestor of anything focusable, produces a control a keyboard reaches
and screen reader software insists does not exist. That combination has its own name and
its own automated rule: see hidden but focusable. If the thing
should not be reachable, it should not be reachable, and hiding it from software is not
how you say so.
The second trap is the same mistake at page scale. aria-hidden is not
inert. It hides from the tree and touches neither the focus order nor hit
testing, so a background marked this way behind a dialog still takes clicks and still
takes Tab stops. Sealing a region needs inert, or a <dialog> opened with
showModal(), which makes everything outside the top layer inert for you. Reach for
aria-hidden when something is genuinely decoration, and for inert when something is
genuinely out of service.
Which word?
| If you want | say |
|---|---|
| hiding something from screen readers but not from eyes | aria-hidden |
| making a whole region unreachable, not just invisible | inert |
| text for screen readers that never shows on screen | visually hidden |
| markup you needed for layout is lying about meaning | presentation role |
| the picture adds nothing a reader would miss | decorative image |
| focus disappears into an offscreen or hidden panel | hidden but focusable |
Related
See also: Accessibility tree