oxc-project/oxc · warning

Ambiguous text within anchor, screen reader users rely on li

Error message

Ambiguous text within anchor, screen reader users rely on link text for context.

What it means

This is the oxlint `jsx-a11y/anchor-ambiguous-text` diagnostic. Screen reader users often browse a links list stripped of surrounding context, so link text like "click here" gives no information. The rule computes an anchor's text from its `aria-label`, child image `alt` text, and text content, and reports when it matches one of the configured ambiguous words (defaults: "click here", "here", "link", "a link", "learn more").

Source

Thrown at crates/oxc_linter/src/rules/jsx_a11y/anchor_ambiguous_text.rs:25

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, get_string_literal_prop_value, has_jsx_prop_ignore_case,
        is_hidden_from_screen_reader,
    },
};

fn anchor_has_ambiguous_text(span: Span, text: &CompactStr) -> OxcDiagnostic {
    OxcDiagnostic::warn(
        "Ambiguous text within anchor, screen reader users rely on link text for context.",
    )
    .with_label(span)
    .with_help(format!("Avoid using ambiguous text like \"{text}\", replace it with more descriptive text that provides context."))
}

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

#[derive(Debug, Clone, JsonSchema, Deserialize)]
#[serde(rename_all = "camelCase", default, deny_unknown_fields)]
pub struct AnchorAmbiguousTextConfig {
    /// List of ambiguous words or phrases that should be flagged in anchor text.
    words: Vec<CompactStr>,
}

impl Default for AnchorAmbiguousTextConfig {
    fn default() -> Self {

View on GitHub (pinned to e1e7af627c)

Solutions

1. Rewrite the link text to describe the destination: `<a href="/tutorial">read the JS parser tutorial</a>`.
2. Keep visual copy but supply context via `aria-label`: `<a href="/docs" aria-label="Read the full API documentation">learn more</a>`.
3. If a listed word is intentional in your product copy, remove it from the rule's `words` config.
4. Disable the rule for purely stylistic disagreements.

Example fix

// before
<a href="/tutorial">click here</a>

// after
<a href="/tutorial">read the parsing tutorial</a>
// or keep the visual copy but label it:
<a href="/tutorial" aria-label="read the parsing tutorial">click here</a>

// Link component that encourages descriptive text at authoring time
type SmartLinkProps = { href: string; children: React.ReactNode; ariaLabel?: string };
const AMBIGUOUS = new Set(['click here', 'here', 'link', 'a link', 'learn more']);
export function SmartLink({ href, children, ariaLabel }: SmartLinkProps) {
  const text = ariaLabel ?? String(children);
  if (AMBIGUOUS.has(text.toLowerCase())) console.warn('ambiguous link text:', text);
  return <a href={href} aria-label={ariaLabel}>{children}</a>;
}

When it happens

Trigger: An anchor element (or a component in its config) resolves to text that equals one of `words` (case-insensitive match of the whole accessible text). Correct text like `read this tutorial`, or an explicit `aria-label="oxc linter documentation"` over "click here", passes.

Common situations: Marketing/table-of-contents links rendered as "learn more" or "here" per copy guidelines; a11y audits tightening link text; teams customizing the `words` array when their product copy legitimately uses a listed phrase.

Related errors

• Missing accessible content when using `a` elements.
• ARIA used where native HTML could suffice.
• Missing `alt` attribute.
• Invalid `alt` value.
• Missing value for `aria-label` attribute.

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