oxc-project/oxc · warning · OxcDiagnostic

Invalid handler name: {handler_name}

Error message

Invalid handler name: {handler_name}

What it means

Diagnostic from the oxlint rule react/jsx-handler-names (crates/oxc_linter/src/rules/react/jsx_handler_names.rs). It fires when a JSX attribute whose prop key is an event-handler prop (matches the eventHandlerPropPrefix regex, default ^on[A-Z].*) is bound to a handler function whose name does not match the handler regex ^((.*\.)?handle)[0-9]*[A-Z].*$ (default eventHandlerPrefix "handle"). The rule exists to keep prop/handler naming symmetric (onChange -> handleChange) for readability and maintainability. It is a lint warning, not a runtime error.

Source

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

    },
};
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::{GetSpan, Span};
use oxc_str::{CompactStr, Ident};
use schemars::{
    JsonSchema, SchemaGenerator,
    schema::{Schema, SchemaObject, SubschemaValidation},
};
use serde_json::Value;

fn bad_handler_name_diagnostic(
    span: Span,
    prop_key: &str,
    handler_name: Option<&str>,
    handler_prefix: &str,
) -> OxcDiagnostic {
    OxcDiagnostic::warn(
        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 {

View on GitHub (pinned to e1e7af627c)

Solutions

1. Rename the handler so it starts with the configured prefix followed by an uppercase letter, e.g. this.handleChange / handle123Change
2. If your convention differs, set eventHandlerPrefix in .oxlintrc.json (pipe-separated alternatives such as "handle|on", or false to disable handler-name checking)
3. Pass props through instead: this.props.onFoo / props.onChange values are accepted as-is by the rule
4. Add the offending element to ignoreComponentNames (supports globs like "MyLib*") when it is a third-party component you cannot rename
5. Disable the rule for the file or project if the naming convention is not enforced

Example fix

// before
<TestComponent onChange={this.doSomethingOnChange} />
<TestComponent onChange={takeCareOfChange} />  // with checkLocalVariables: true

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

# fail CI before merge when handler names violate the convention
npx oxlint -D react/jsx-handler-names src/

When it happens

Trigger: A JSX attribute like key="onChange" (or any key matching the configured eventHandlerPropPrefix) whose value expression fails the handler-name regex: <TestComponent onChange={this.doSomethingOnChange} /> (member expression, checked by default), this.handle (no uppercase after prefix), this.handle4change (lowercase after prefix), this.props.obj.onChange, a local identifier like takeCareOfChange (requires checkLocalVariables: true), or an arrow call like () => this.takeCareOfChange() (requires checkInlineFunction: true). Custom prefixes set via eventHandlerPrefix (pipe-separated list or false) change what matches.

Common situations: Teams migrating from eslint-plugin-react with a different convention (e.g. handlers named onFoo, requiring eventHandlerPrefix: "handle|on"); class components passing this.props.obj.onChange chains; enabling checkLocalVariables/checkInlineFunctions to match an old .eslintrc and suddenly seeing many new reports; third-party components with proprietary prop names that need ignoreComponentNames.

Related errors

• Bad handler name
• Invalid handler prop name: {prop_key}
• JSX component {component_name} must be in PascalCase or SCRE
• JSX component {component_name} must be in PascalCase
• `button` elements must have an explicit `type` attribute.

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