oxc-project/oxc · warning · OxcDiagnostic

Invalid handler prop name: {prop_key}

Error message

Invalid handler prop name: {prop_key}

What it means

Third diagnostic of react/jsx-handler-names, the mirror case of the handler-name check: the value IS a correctly named handler (matches ^((.*\.)?handle)[0-9]*[A-Z].*$), but the JSX prop key itself is not an event-handler prop name (does not match the eventHandlerPropPrefix regex, default ^on[A-Z].*). The rule wants handler-valued props to be named onX, e.g. <MyComponent onChange={this.handleChange} /> instead of <MyComponent handleChange={this.handleChange} />. Member-expression values (this.handleChange, x.handleFoo) are checked even with the default config because checkLocalVariables/checkInlineFunction only gate identifiers and arrows.

Source

Thrown at crates/oxc_linter/src/rules/react/jsx_handler_names.rs:47

        if let Some(handler_name) = handler_name {
            format!("Invalid handler name: {handler_name}")
        } else {
            "Bad handler name".to_string()
        },
    )
        .with_help(format!(
            "Handler function for {prop_key} prop key must be a camelCase name beginning with \'{handler_prefix}\' only"
        ))
        .with_label(span)
}

fn bad_handler_prop_name_diagnostic(
    span: Span,
    prop_key: &str,
    prop_value: Option<&str>,
    handler_prop_prefix: &str,
) -> OxcDiagnostic {
    OxcDiagnostic::warn(format!("Invalid handler prop name: {prop_key}"))
        .with_help(if let Some(prop_value) = prop_value {
            format!("Prop key for {prop_value} must begin with \'{handler_prop_prefix}\'")
        } else {
            format!("Prop key must begin with \'{handler_prop_prefix}\'")
        })
        .with_label(span)
}

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

#[derive(Debug, Clone, JsonSchema)]
#[serde(rename_all = "camelCase", default, deny_unknown_fields)]
pub struct JsxHandlerNamesConfig {
    /// Whether to check for inline functions in JSX attributes.
    #[serde(rename = "checkInlineFunction")]
    check_inline_functions: bool,
    /// Whether to check for local variables in JSX attributes.

View on GitHub (pinned to e1e7af627c)

Solutions

1. Rename the prop key to the on-prefixed form: <MyComponent onChange={this.handleChange} />
2. If your prop naming convention differs, set eventHandlerPropPrefix in .oxlintrc.json to your prefix (pipe-separated list such as "when|on")
3. Set eventHandlerPropPrefix: false to stop checking prop-key names entirely while still checking handler names
4. Add the component to ignoreComponentNames if it is a third-party component with a fixed API

Example fix

// before
<TestComponent handleChange={this.handleChange} />
<TestComponent only={this.handleChange} />

// after
<TestComponent onChange={this.handleChange} />

npx oxlint -D react/jsx-handler-names src/

When it happens

Trigger: Any JSX attribute whose value resolves to a handle-prefixed function while the key lacks the 'on' prefix: <TestComponent only={this.handleChange} />, <TestComponent handleChange={this.handleChange} />, or with checkLocalVariables: true, <TestComponent whenChange={handleChange} />. Custom eventHandlerPropPrefix (e.g. "when|on" or false to disable prop-name checking) changes which keys pass.

Common situations: Components exposing handleX-style props by mistake; teams whose prop convention is not 'on'-prefixed (must reconfigure eventHandlerPropPrefix or set it to false); migrating a codebase that only ever used the handler-name half of the rule.

Related errors

• Invalid handler name: {handler_name}
• Bad handler name
• No duplicate props allowed. The prop "{prop_name}" is duplic
• JSX component {component_name} must be in PascalCase or SCRE
• JSX component {component_name} must be in PascalCase

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