Skip to main content
Checks that heading levels don’t skip
Rule IDa11y/heading-order
CategoryAccessibility
ScopePer-page
Severitywarning
Weight4/10

​
Solution

Headings should follow a logical hierarchy without skipping levels. Screen reader users navigate by headings, so skipping from H1 to H3 is confusing. Correct order: H1 -> H2 -> H3 (not H1 -> H3). You can have multiple headings at the same level, and you can go back up (H3 -> H2 is fine). Think of headings as an outline - they should make sense when read alone.

​
Enable / Disable

​
Disable this rule

squirrel.toml
[rules]
disable = ["a11y/heading-order"]

​
Disable all Accessibility rules

squirrel.toml
[rules]
disable = ["a11y/*"]

​
Enable only this rule

squirrel.toml
[rules]
enable = ["a11y/heading-order"]
disable = ["*"]