oxc-project/oxc · error · OxcDiagnostic

Invalid `alt` value.

Error message

Invalid `alt` value.

What it means

This is the oxlint `jsx-a11y/alt-text` diagnostic for an `img` whose `alt` attribute exists but has an unusable value. The rule treats an `alt` as invalid when it has no value at all (`<img alt>`) or when it is an expression container evaluating to `null`/`undefined`. The point: alt is only useful when it is a real string (or an intentionally empty one).

Source

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

use crate::{
    AstNode,
    context::LintContext,
    rule::Rule,
    utils::{
        get_element_type, get_prop_value, get_string_literal_prop_value, has_jsx_prop_ignore_case,
        object_has_accessible_child,
    },
};

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)
}

View on GitHub (pinned to e1e7af627c)

Solutions

1. Give alt a real value or `""` for decorative images: `alt={maybeAlt ?? ""}`.
2. Remove bare `<img alt>` and write `alt="..."`.
3. Check the expression feeding `alt={...}` never evaluates to `null`/`undefined`.

Example fix

// before
<img src={src} alt={undefined} />
<img src={src} alt />

// after
<img src={src} alt={description} />
<img src={src} alt="" />

// Keep alt non-nullish at the boundary
const altText = maybeAlt ?? ''; // '' = decorative, never undefined
return <img src={src} alt={altText} />;

When it happens

Trigger: `img_rule` finds an `alt` prop (case-insensitive) but `is_valid_alt_prop` returns false: `get_prop_value` is `None` (bare attribute) or the JSX expression is `null`/`undefined` (`alt={undefined}`, `alt={null}`). Note the rule returns early once any `alt` prop exists, so missing aria fallbacks are not additionally reported.

Common situations: Conditionally computed alt (`alt={maybeAlt}` where the fallback branch yields `undefined`); spreading defaults then overriding with `alt={null}`; forgetting to give the attribute a value in JSX.

Related errors

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

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