oxc-project/oxc · error

Headings must have content and the content must be accessibl

Error message

Headings must have content and the content must be accessible by a screen reader.

What it means

Fires from jsx-a11y/heading-has-content when a heading element (h1-h6) contains no content, or only content hidden from screen readers (aria-hidden). The run visitor checks heading elements and their accessible children; the helper advises providing screen-reader-accessible content.

Source

Thrown at crates/oxc_linter/src/rules/jsx_a11y/heading_has_content.rs:17

use oxc_ast::AstKind;
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;
use oxc_str::CompactStr;
use schemars::JsonSchema;
use serde::Deserialize;

use crate::{
    AstNode,
    context::LintContext,
    rule::{DefaultRuleConfig, Rule},
    utils::{get_element_type, is_hidden_from_screen_reader, object_has_accessible_child},
};

fn heading_has_content_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn(
        "Headings must have content and the content must be accessible by a screen reader.",
    )
    .with_help("Provide screen reader accessible content when using heading elements.")
    .with_label(span)
}

#[derive(Debug, Default, Clone, Deserialize)]
pub struct HeadingHasContent(Box<HeadingHasContentConfig>);

#[derive(Debug, Default, Clone, PartialEq, Eq, JsonSchema, Deserialize)]
#[serde(rename_all = "camelCase", default, deny_unknown_fields)]
pub struct HeadingHasContentConfig {
    /// Additional custom component names to treat as heading elements.
    /// These will be validated in addition to the standard h1-h6 elements.
    components: Option<Vec<CompactStr>>,
}

impl std::ops::Deref for HeadingHasContent {

View on GitHub (pinned to e1e7af627c)

Solutions

1. Add text content inside the heading
2. If content is hidden, provide an accessible alternative such as `aria-label`
3. Use a non-heading element if the heading is purely decorative

When it happens

Trigger: Thrown at crates/oxc_linter/src/rules/jsx_a11y/heading_has_content.rs:17 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of oxc-project/oxc@e1e7af627c (2026-08-20). Data as JSON: /api/errors/98914e1e2b4a9138. Report an issue: GitHub.