I want an HTML attribute to reset and isolate the heading hierarchy within a container element
Submitted by Joppe Kroon
Permalink https://webwewant.fyi/wants/8c2fbe47-3791-4739-ac6f-718573a2bd86/
This idea is currently being discussed.
I want an HTML attribute that lets me declare that a container element starts a fresh, isolated heading tree, so that web components and reusable content blocks can safely use h1-level headings without disrupting the heading structure of the surrounding page.
HTML's original outline algorithm promised that sectioning elements (<article>, <section>, etc.) would create nested heading contexts, meaning the same <h1> inside two different sections would be ranked appropriately in the accessibility tree. In practice, that algorithm was never implemented by browsers and has since been removed from the specification. The practical result is that all headings on a page compete in a single flat hierarchy, regardless of what element they are nested inside.
This creates a real problem for reusable components and web components. When I author a standalone component -- a card, a widget, a document viewer -- I do not know at what heading level it will be placed in the consuming page. To avoid breaking the page's heading structure, I must either:
- Pick a conservatively low heading level like
h5orh6, which hobbles the internal structure of my own component. - Rely on a slot-based or JavaScript-driven approach where the consumer passes the correct starting heading level as a prop, adding friction and fragility.
A declarative attribute such as heading-root or heading-scope on any container element would instruct the browser and accessibility tree to treat the contained headings as a self-contained subtree, resetting the rank to h1 within that boundary. This would allow:
- Web component authors to use semantically correct headings inside their components regardless of where those components are embedded.
- CMS and documentation platforms to render contributed content blocks with independent heading structures.
- Assistive technology to present a coherent nested outline instead of a flat, confusing list of headings pulled from across independent components.
This feature is increasingly urgent as the lines between documents and applications blur. PWAs and component-driven architectures now regularly compose pages from isolated pieces of UI, each of which deserves its own logical heading hierarchy.
- Votes
- 0
What are votes for and how are they tallied?