🎉 A11y Issue Detection Agent is now live! Detect accessibility issues like a WCAG expert with AI. Try now!
No Result Found
Connect and get help from 7,000+ developers on our Discord community. Ask the CommunityAsk the Community

Incorrect heading

Screen reader users rely on headings to navigate app content. When elements that do not introduce sections of content are programmatically marked as headings, screen readers announce false structural cues that mislead users and make heading-based navigation unreliable. This rule ensures that only elements genuinely functioning as headings carry the heading trait, and that heading text clearly describes the content that follows.

  • Rule Category : Content Structure
  • Rule Severity : Serious
  • WCAG 2.1 & 2.2 SC : 1.3.1 (A), 2.4.6 (AA)
  • Supported Platforms : Android, iOS, React Native, Flutter

Success criteria

The rule checks for the following:

  • Elements that do not introduce or organize a section of content must not be programmatically marked with the heading trait.
  • Headings must be descriptive, clearly indicating the topic or purpose of the content that follows them.

AI-powered testing

BrowserStack provides an AI-powered Issue Detection Agent that analyzes app screenshots and element properties to identify elements that are programmatically marked as headings but do not genuinely function as headings. If an incorrect heading is detected, the agent provides contextual reasoning and an actionable suggestion.

AI-powered results are clearly marked in the report so you can review and apply suggestions as needed.

The Issue Detection Agent performs the following checks:

  • Detects incorrect headings
    1. Identifies elements that are programmatically marked as headings but do not introduce or organize a section of content. The Issue Detection Agent checks for the following:
      • Decorative or promotional text, such as marketing slogans or stat numbers, marked with the heading trait.
      • Interactive elements such as buttons, links, or tab-bar icons that are marked as headings.
      • Detail or metadata text, such as timestamps or engagement counts, marked as headings.
    2. Identifies headings where the text does not adequately describe the topic or purpose of the content that follows.
  • Suggests fixes
    • For elements that are not structural headings, explains why the heading trait should be removed.
    • For headings that are not descriptive, suggests more suitable heading text.

For more information about the Issue Detection Agent, see Issue Detection Agent.

How to fix

To resolve incorrect heading violations, remove the heading trait from the text element using the appropriate framework attribute:

To fix this violation:

  1. Remove the heading trait from text elements that should not function as a heading. On Android, this can be done in two ways:
    • In layout XML, remove the android:accessibilityHeading="true" attribute or explicitly set it to false.
    • In code, call ViewCompat.setAccessibilityHeading(view, false).
  2. Ensure text elements that act as headings are descriptive, clearly indicating the topic or purpose of the content.

To fix this violation:

  1. Remove the heading trait from text elements that should not function as a heading. To do so on iOS, remove the UIAccessibilityTraitHeader trait.
  2. Ensure text elements that act as headings are descriptive, clearly indicating the topic or purpose of the content.

To fix this violation:

  1. Remove the heading trait from text elements that should not function as a heading. To do so in React Native, remove the accessibilityRole="header" prop or replace it with the appropriate role.
  2. Ensure text elements that act as headings are descriptive, clearly indicating the topic or purpose of the content.

To fix this violation:

  1. Remove the heading trait from text elements that should not function as a heading. To do so in Flutter, remove the Semantics widget with header: true, or set header: false.
  2. Ensure text elements that act as headings are descriptive, clearly indicating the topic or purpose of the content.

Example

The following screenshot shows an incorrect heading violation in an Android app:

Incorrect heading violation showing a profile detail text element that is programmatically marked as a heading in a social networking app.

Error

  • In this example, the text element “Based in Bengaluru · 3d ago” is programmatically marked as a heading, with isHeading: true. This text is profile detail information about a user. It does not introduce a new section of content. As a result, screen readers announce it as a heading, creating false navigational cues.

Fix

  • To fix this violation, ensure the text element is not programmatically marked as a heading:
    • In this example, set the Android heading attribute, android:accessibilityHeading for the text element to false.

References

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked





Thank you for your valuable feedback

Is this page helping you?

Yes
No

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked





Thank you for your valuable feedback!

Talk to an Expert
Download Copy Check Circle