oxc-project/oxc · error

A control must be associated with a text label.

Error message

A control must be associated with a text label.

What it means

Fires from jsx-a11y/control-has-associated-label when an element classified as a control (per the rule's controls list, e.g. dropdown, menu, autocomplete) has no accessible text label. The run visitor skips hidden elements and interactive elements with roles; unlabeled controls get this diagnostic.

Source

Thrown at crates/oxc_linter/src/rules/jsx_a11y/control_has_associated_label.rs:28

use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;
use oxc_str::CompactStr;

use crate::{
    AstNode,
    context::LintContext,
    globals::HTML_TAG,
    rule::{DefaultRuleConfig, Rule},
    utils::{
        get_element_type, get_jsx_attribute_name, get_string_literal_prop_value, has_jsx_prop,
        is_hidden_from_screen_reader, is_interactive_element, is_interactive_role,
        is_react_component_name,
    },
};

fn control_has_associated_label_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("A control must be associated with a text label.")
        .with_help(
            "Add a text label to the control element. This can be done by adding text content, an `aria-label` attribute, or an `aria-labelledby` attribute.",
        )
        .with_label(span)
}

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

/// Elements that are always ignored (cannot reliably determine label source).
const ALWAYS_IGNORE_ELEMENTS: [&str; 1] = ["link"];

const DEFAULT_IGNORE_ELEMENTS: [&str; 7] =
    ["audio", "canvas", "embed", "input", "textarea", "tr", "video"];

const DEFAULT_IGNORE_ROLES: [&str; 10] = [
    "grid",
    "listbox",

View on GitHub (pinned to e1e7af627c)

Solutions

1. Add an aria-label, aria-labelledby, or visible text label to the control
2. Associate an existing label element with the control via htmlFor/id

When it happens

Trigger: Thrown at crates/oxc_linter/src/rules/jsx_a11y/control_has_associated_label.rs:28 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/3958fe230d926610. Report an issue: GitHub.