oxc-project/oxc · error

A form label must be associated with a control.

Error message

A form label must be associated with a control.

What it means

Raised by jsx-a11y/label-has-associated-control when a <label> is not linked to any form control, either via htmlFor pointing to an input id or by nesting the control inside the label. Unassociated labels are ignored by screen readers.

Source

Thrown at crates/oxc_linter/src/rules/jsx_a11y/label_has_associated_control.rs:22

    AstKind,
    ast::{JSXAttributeItem, JSXAttributeValue, JSXChild, JSXElement},
};
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;
use oxc_str::CompactStr;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

use crate::{
    AstNode,
    context::LintContext,
    rule::Rule,
    utils::{get_element_type, get_jsx_attribute_name, has_jsx_prop, is_react_component_name},
};

fn label_has_associated_control_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("A form label must be associated with a control.")
        .with_help("Either give the label a `htmlFor` attribute with the id of the associated control, or wrap the label around the control.")
        .with_label(span)
}

fn label_has_associated_control_diagnostic_no_label(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("A form label must have accessible text.")
        .with_help("Ensure the label either has text inside it or is accessibly labelled using an attribute such as `aria-label`, or `aria-labelledby`. You can mark more attributes as accessible labels by configuring the `labelAttributes` option.")
        .with_label(span)
}

#[derive(Debug, Default, Clone)]
pub struct LabelHasAssociatedControl(Box<LabelHasAssociatedControlConfig>);

const DEFAULT_CONTROL_COMPONENTS: [&str; 6] =
    ["input", "meter", "output", "progress", "select", "textarea"];

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase", default, deny_unknown_fields)]

View on GitHub (pinned to e1e7af627c)

Solutions

1. Add htmlFor to the label matching the control's id.
2. Wrap the input inside the label element.
3. Add aria-label to the control if a visible label is not possible.

When it happens

Trigger: Thrown at crates/oxc_linter/src/rules/jsx_a11y/label_has_associated_control.rs:22 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/64a2d4c679a4509f. Report an issue: GitHub.