oxc-project/oxc · error

Elements with ARIA roles must use a valid, non-abstract ARIA

Error message

Elements with ARIA roles must use a valid, non-abstract ARIA role.

What it means

Fires from jsx-a11y/aria-role when an element's role attribute is not one of the valid, non-abstract ARIA roles (e.g. a typo or an abstract role like 'widget'). The helper appends a contextual help suffix describing valid roles and labels the attribute span.

Source

Thrown at crates/oxc_linter/src/rules/jsx_a11y/aria_role.rs:20

    AstKind,
    ast::{JSXAttributeItem, JSXAttributeValue, JSXExpression},
};
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;
use schemars::JsonSchema;
use serde::Deserialize;

use crate::{
    AstNode,
    context::LintContext,
    globals::{HTML_TAG, VALID_ARIA_ROLES},
    rule::{DefaultRuleConfig, Rule},
    utils::{get_element_type, get_prop_value, has_jsx_prop},
};

fn aria_role_diagnostic(span: Span, help_suffix: &str) -> OxcDiagnostic {
    OxcDiagnostic::warn("Elements with ARIA roles must use a valid, non-abstract ARIA role.")
        .with_help(format!(
            "Set a valid, non-abstract ARIA role for element with ARIA{help_suffix}"
        ))
        .with_label(span)
}

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

#[derive(Debug, Default, Clone, JsonSchema, Deserialize)]
#[serde(rename_all = "camelCase", default, deny_unknown_fields)]
pub struct AriaRoleConfig {
    /// Determines if developer-created components are checked.
    #[serde(rename = "ignoreNonDOM")]
    ignore_non_dom: bool,
    /// Custom roles that should be allowed in addition to the ARIA spec.
    allowed_invalid_roles: Vec<String>,
}

View on GitHub (pinned to e1e7af627c)

Solutions

1. Use a valid, non-abstract ARIA role name
2. Rely on the element's implicit role and remove the explicit `role` attribute

When it happens

Trigger: Thrown at crates/oxc_linter/src/rules/jsx_a11y/aria_role.rs:20 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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