oxc-project/oxc · warning

ARIA used where native HTML could suffice.

Error message

ARIA used where native HTML could suffice.

What it means

Diagnostic from oxlint's jsx-a11y alt-text rule, produced by its `prefer_alt` helper. When an element that requires a text alternative (img, object, area, input[type=image]) is marked decorative with role="presentation" or role="none" instead of using the native attribute, the rule says ARIA was used where native HTML could suffice. The first rule of ARIA is to prefer native semantics, and `alt=""` is the standard way to hide decorative images from screen readers.

Source

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

            "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.")
        .with_help("Each area of an image map must have a text alternative through the `alt`, `aria-label`, or `aria-labelledby` prop.")
        .with_label(span)
}

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

View on GitHub (pinned to e1e7af627c)

Solutions

1. For decorative images use the empty native attribute: `<img src="..." alt="" />`.
2. If the image conveys information, give it meaningful alt text instead of a presentation role.
3. Remove the redundant role attribute once alt is present.

Example fix

// before
<img src="divider.png" role="presentation" />

// after
<img src="divider.png" alt="" />

oxlint --jsx-a11y-plugin src/ # alt-text rule checks img/object/area/input[image]

When it happens

Trigger: An img/area/object/image-input JSXOpeningElement that has a role attribute resolving to a presentation role and no alt, per the `has_jsx_prop_ignore_case(node, "role").is_some_and(is_presentation_role)` check that emits `prefer_alt(node.span)` — e.g. `<img src="divider.png" role="presentation" />`. Adding `alt=""` (even `alt={undefined}` is treated as missing) silences it.

Common situations: Decorative dividers/spacers/background images given role="presentation" copied from older a11y guides; teams switching from aria-hidden to role="none"; designers' placeholder markup.

Related errors

• Missing `alt` attribute.
• Invalid `alt` value.
• 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/ceab92015a6b569c. Report an issue: GitHub.