{"record":{"id":"856adadb1598267a","repo":"oxc-project/oxc","slug":"prefer-tag-over-role-attribute-role","errorCode":null,"errorMessage":"Prefer `{tag}` over `role` attribute `{role}`.","messagePattern":"Prefer `(.+?)` over `role` attribute `(.+?)`\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"crates/oxc_linter/src/rules/jsx_a11y/prefer_tag_over_role.rs","lineNumber":17,"sourceCode":"use oxc_ast::{\n    AstKind,\n    ast::{JSXAttributeItem, JSXAttributeValue},\n};\nuse oxc_diagnostics::OxcDiagnostic;\nuse oxc_macros::declare_oxc_lint;\nuse oxc_span::Span;\n\nuse crate::{\n    AstNode,\n    context::LintContext,\n    rule::Rule,\n    utils::{get_element_type, get_tags_for_role, has_jsx_prop_ignore_case},\n};\n\nfn prefer_tag_over_role_diagnostic(span: Span, tag: &str, role: &str) -> OxcDiagnostic {\n    OxcDiagnostic::warn(format!(\"Prefer `{tag}` over `role` attribute `{role}`.\"))\n        .with_help(format!(\"Replace HTML elements with `role` attribute `{role}` to corresponding semantic HTML tag `{tag}`.\"))\n        .with_label(span)\n}\n\n#[derive(Debug, Default, Clone)]\npub struct PreferTagOverRole;\n\ndeclare_oxc_lint!(\n    /// ### What it does\n    ///\n    /// Enforces using semantic HTML tags over `role` attribute.\n    ///\n    /// ### Why is this bad?\n    ///\n    /// Using semantic HTML tags can improve accessibility and readability of the code.\n    ///\n    /// ### Examples\n    ///","sourceCodeStart":1,"sourceCodeEnd":35,"githubUrl":"https://github.com/oxc-project/oxc/blob/e1e7af627c8843ab64044ed466b128fcc21a035b/crates/oxc_linter/src/rules/jsx_a11y/prefer_tag_over_role.rs#L1-L35","documentation":"This is the `jsx_a11y/prefer-tag-over-role` rule in oxlint. It fires when an element with an explicit ARIA role has a native HTML element that provides that role for free (via `get_tags_for_role`), e.g. `<div role=\"button\">`. Native elements carry built-in keyboard behavior and semantics, so the tag is preferred over the role override.","triggerScenarios":"A JSX element (resolved via `get_element_type`) with a `role` attribute whose value maps to one or more recommended semantic tags in the role->tags table, while the element itself is not one of those tags.","commonSituations":"Div-based buttons (`role=\"button\"`), div headings (`role=\"heading\"`), nav-like divs (`role=\"navigation\"`) written before teams adopted semantic HTML; component libraries overriding roles on generic containers.","solutions":["Swap the element for the semantic tag the rule names (e.g. `<button>`, `<nav>`, `<table>`) and drop the `role`.","Carry over styling via className; reset browser defaults (all: unset / appearance: none) where looks matter.","If the wrapper structure must stay, keep the interactive tag on the innermost operable node instead."],"exampleFix":"// before\n<div role=\"button\" tabIndex={0} onClick={submit}>Submit</div>\n\n// after\n<button type=\"button\" onClick={submit}>Submit</button>","handlingStrategy":"validation","validationCode":"npx oxlint --jsx-a11y/prefer-tag-over-role src/","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Start every new interactive component from a semantic tag.","Treat role overrides on generic containers as code smell in review.","When the rule names a tag, adopt it rather than suppressing the diagnostic."],"tags":["jsx-a11y","react","accessibility","semantic-html","aria-roles","lint"],"backgroundTag":"prefer-semantic-html-over-role","analyzedSha":"e1e7af627c8843ab64044ed466b128fcc21a035b","analyzedAt":"2026-08-20T07:01:07.079Z","contentChangedAt":"2026-08-20T07:01:07.079Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}