oxc-project/oxc · error · OxcDiagnostic

Missing value for `aria-labelledby` attribute.

Error message

Missing value for `aria-labelledby` attribute.

What it means

This is the oxlint `jsx-a11y/alt-text` diagnostic for an `img` with neither `alt` nor a valued `aria-label`, but with an `aria-labelledby` attribute that has no usable value. `aria-labelledby` must reference the id of a label element; an empty or undefined value leaves the image unnamed.

Source

Thrown at crates/oxc_linter/src/rules/jsx_a11y/alt_text.rs:42

        .with_label(span)
}

fn missing_alt_value(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Invalid `alt` value.")
        .with_help(
            "Must have meaningful value for `alt` prop. Use alt=\"\" for presentational images.",
        )
        .with_label(span)
}

fn aria_label_value(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Missing value for `aria-label` attribute.")
        .with_help("Give `aria-label` a meaningful value. Prever the `alt` attribute over `aria-label` for images.")
        .with_label(span)
}

fn aria_labelled_by_value(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Missing value for `aria-labelledby` attribute.")
        .with_help("Give `aria-labelledby` an ID to a label element. Prefer the `alt` attribute over `aria-labelledby` for images.")
        .with_label(span)
}

fn prefer_alt(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("ARIA used where native HTML could suffice.")
        .with_help("Prefer alt=\"\" over presentational role. Native HTML attributes should be preferred for accessibility before resorting to ARIA attributes.")
        .with_label(span)
}

fn object(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Missing alternative text.")
        .with_help("Embedded <object> elements must have a text alternative through the `alt`, `aria-label`, or `aria-labelledby` prop.")
        .with_label(span)
}

fn area(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Missing alternative text.")

View on GitHub (pinned to e1e7af627c)

Solutions

1. Point `aria-labelledby` at a real element id: `aria-labelledby="chart-caption"` next to `<p id="chart-caption">`.
2. Prefer plain `alt` text when there is no visible caption to reference.
3. Ensure the expression feeding the attribute never renders empty.

Example fix

// before
<img src={src} aria-labelledby="" />

// after
<p id="hero-caption">Sunrise over the bay</p>
<img src={src} aria-labelledby="hero-caption" />

// Render aria-labelledby only when the target id is known
const captionId = caption ? 'hero-caption' : undefined;
<>
  {caption && <p id="hero-caption">{caption}</p>}
  <img src={src} aria-labelledby={captionId} alt="" />
</>

When it happens

Trigger: `img_rule` finds an `aria-labelledby` prop (after no `alt` and no valid `aria-label`) where the value is an empty string literal or an undefined/non-expression container per `aria_label_has_value`.

Common situations: Passing a label id that is conditionally computed and can be `undefined`; refactors that renamed the target element's id but left `aria-labelledby=""` placeholders.

Related errors

• Missing value for `aria-label` attribute.
• ARIA used where native HTML could suffice.
• Missing `alt` attribute.
• Invalid `alt` value.
• Missing alternative text.

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