oxc-project/oxc · error · OxcDiagnostic

Missing value for `aria-label` attribute.

Error message

Missing value for `aria-label` attribute.

What it means

This is the oxlint `jsx-a11y/alt-text` diagnostic for an `img` that has no `alt` but does have `aria-label`, and the `aria-label` carries no value. The rule accepts `aria-label` as an alternative to `alt` only when it is non-empty; an empty or undefined `aria-label` names the image for no one.

Source

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

    },
};

fn missing_alt_prop(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Missing `alt` attribute.")
        .with_help("Must have `alt` prop, either with meaningful text, or an empty string for decorative images.")
        .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.")

View on GitHub (pinned to e1e7af627c)

Solutions

1. Provide a non-empty label or switch back to `alt`: `<img src={src} alt={name} />` (the help text itself says prefer `alt`).
2. Fix dynamic label logic so `aria-label` is always a non-empty string when rendered.
3. Use `aria-labelledby` pointing at a visible caption instead.

Example fix

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

// after
<img src={src} alt="Company headquarters" />

// Ensure aria-label is a non-empty string before rendering it on an img
const label = typeof maybeLabel === 'string' && maybeLabel.trim() !== '' ? maybeLabel : undefined;
return label ? <img src={src} aria-label={label} /> : <img src={src} alt="" />;

When it happens

Trigger: `img_rule` finds no `alt`, no presentation role, and an `aria-label` prop for which `aria_label_has_value` is false: empty string literal (`aria-label=""`) or an expression container that is not a real expression / is `undefined`.

Common situations: Teams switching from `alt` to `aria-label` per design-system guidance but leaving the value blank; dynamic labels that default to `undefined`.

Related errors

• Missing value for `aria-labelledby` 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/8a5667930b80233e. Report an issue: GitHub.