{"record":{"id":"c82b38e2cc8be477","repo":"oxc-project/oxc","slug":"ambiguous-text-within-anchor-screen-reader-users","errorCode":null,"errorMessage":"Ambiguous text within anchor, screen reader users rely on link text for context.","messagePattern":"Ambiguous text within anchor, screen reader users rely on link text for context\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"crates/oxc_linter/src/rules/jsx_a11y/anchor_ambiguous_text.rs","lineNumber":25,"sourceCode":"use oxc_diagnostics::OxcDiagnostic;\nuse oxc_macros::declare_oxc_lint;\nuse oxc_span::Span;\nuse oxc_str::CompactStr;\nuse schemars::JsonSchema;\nuse serde::Deserialize;\n\nuse crate::{\n    AstNode,\n    context::LintContext,\n    rule::{DefaultRuleConfig, Rule},\n    utils::{\n        get_element_type, get_string_literal_prop_value, has_jsx_prop_ignore_case,\n        is_hidden_from_screen_reader,\n    },\n};\n\nfn anchor_has_ambiguous_text(span: Span, text: &CompactStr) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\n        \"Ambiguous text within anchor, screen reader users rely on link text for context.\",\n    )\n    .with_label(span)\n    .with_help(format!(\"Avoid using ambiguous text like \\\"{text}\\\", replace it with more descriptive text that provides context.\"))\n}\n\n#[derive(Debug, Default, Clone, Deserialize)]\npub struct AnchorAmbiguousText(Box<AnchorAmbiguousTextConfig>);\n\n#[derive(Debug, Clone, JsonSchema, Deserialize)]\n#[serde(rename_all = \"camelCase\", default, deny_unknown_fields)]\npub struct AnchorAmbiguousTextConfig {\n    /// List of ambiguous words or phrases that should be flagged in anchor text.\n    words: Vec<CompactStr>,\n}\n\nimpl Default for AnchorAmbiguousTextConfig {\n    fn default() -> Self {","sourceCodeStart":7,"sourceCodeEnd":43,"githubUrl":"https://github.com/oxc-project/oxc/blob/e1e7af627c8843ab64044ed466b128fcc21a035b/crates/oxc_linter/src/rules/jsx_a11y/anchor_ambiguous_text.rs#L7-L43","documentation":"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\").","triggerScenarios":"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.","commonSituations":"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.","solutions":["Rewrite the link text to describe the destination: `<a href=\"/tutorial\">read the JS parser tutorial</a>`.","Keep visual copy but supply context via `aria-label`: `<a href=\"/docs\" aria-label=\"Read the full API documentation\">learn more</a>`.","If a listed word is intentional in your product copy, remove it from the rule's `words` config.","Disable the rule for purely stylistic disagreements."],"exampleFix":"// before\n<a href=\"/tutorial\">click here</a>\n\n// after\n<a href=\"/tutorial\">read the parsing tutorial</a>\n// or keep the visual copy but label it:\n<a href=\"/tutorial\" aria-label=\"read the parsing tutorial\">click here</a>","handlingStrategy":"validation","validationCode":"// Link component that encourages descriptive text at authoring time\ntype SmartLinkProps = { href: string; children: React.ReactNode; ariaLabel?: string };\nconst AMBIGUOUS = new Set(['click here', 'here', 'link', 'a link', 'learn more']);\nexport function SmartLink({ href, children, ariaLabel }: SmartLinkProps) {\n  const text = ariaLabel ?? String(children);\n  if (AMBIGUOUS.has(text.toLowerCase())) console.warn('ambiguous link text:', text);\n  return <a href={href} aria-label={ariaLabel}>{children}</a>;\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Write link text that names the destination even out of context (imagine a bare links list).","Use `aria-label` when visual copy must stay short.","Customize the rule's `words` array only for phrases your copy team has cleared.","Review link text during a11y audits alongside alt text."],"tags":["jsx-a11y","accessibility","link-text","screen-reader","react","lint","oxlint"],"backgroundTag":"jsx-a11y-ambiguous-link-text","analyzedSha":"e1e7af627c8843ab64044ed466b128fcc21a035b","analyzedAt":"2026-08-20T07:01:07.079Z","contentChangedAt":"2026-08-20T07:01:07.079Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}