How to fix Warning: Unknown event handler property `on` in React

ReactBEGINNERLOWUpdated Dec 10, 2025· 120 views

This warning occurs when React encounters an event handler property starting with "on" that it doesn't recognize as a valid DOM event. This typically happens due to typos in event names, using custom event handlers on DOM elements, or incorrectly spreading props to native HTML elements.

Quick fix

Fixes Warning: Unknown event handler property `on`

// Example of problematic code that might trigger the warning
function MyComponent({ onSpecialClick, ...props }) {
  return <div onSpecialClick={onSpecialClick} {...props} />;
}
  1. Identify the exact problematic prop from the warning
  2. Check for typos in standard event handler names
  3. Filter non-DOM props when spreading to DOM elements
  4. Use data-* attributes for custom DOM data instead of custom props
react — error
// Example of problematic code that might trigger the warning
function MyComponent({ onSpecialClick, ...props }) {
  return <div onSpecialClick={onSpecialClick} {...props} />;
}
Warning: Unknown event handler property `on`

What this error means

React maintains a whitelist of known DOM attributes and event handlers. When you pass a prop starting with "on" to a native DOM element (like <div>, <button>, etc.) that React doesn't recognize, it assumes you're trying to attach an event handler but can't find a corresponding event in its synthetic event system. React warns you because the handler won't work as expected, and the property will be attached directly to the DOM node, which can cause performance issues and unexpected behavior. This warning helps catch common mistakes like misspelled event names (e.g., "onclick" instead of "onClick") or attempting to use custom event handlers on DOM elements without proper setup. React's synthetic event system wraps native browser events for cross-browser compatibility, so unrecognized "on" properties can't be properly managed.

Typical symptoms

  • Yellow warning in browser console: "Warning: Unknown event handler property `on...`. Did you mean `onClick`?"
  • Event handler function doesn't fire when expected event occurs
  • Component renders normally but interactive functionality is broken
  • Warning appears when using prop spreading (`{...props}`) on DOM elements
  • Custom event handlers fail silently without error messages

Common causes

  1. Misspelling standard React event handlers (e.g., "onclick" instead of "onClick", "onMouseenter" instead of "onMouseEnter")
  2. Spreading props containing custom event handlers to DOM elements without filtering
  3. Using custom event handler names on native DOM elements (e.g., `onSpecialEvent` on a <div>)
  4. Passing React-component-only props (like Redux dispatch, context values) to DOM elements
  5. Case sensitivity issues - React event handlers must use camelCase, not lowercase or kebab-case
  6. Using uppercase letters incorrectly in event handler names

How to fix "Warning: Unknown event handler property `on`"

1Identify the exact problematic prop from the warning

Look at the warning in your browser console. React will show the exact prop name and component location. For example: "Warning: Unknown event handler property onSpecialClick. Did you mean onClick?" Locate this component in your codebase.

jsx
// Example of problematic code that might trigger the warning
function MyComponent({ onSpecialClick, ...props }) {
  return <div onSpecialClick={onSpecialClick} {...props} />;
}
2Check for typos in standard event handler names

Review all event handler props in the component. Standard React events use camelCase:

jsx
// ✅ CORRECT - camelCase
<button onClick={handleClick}>
  Click me
</button>

<button onMouseEnter={handleMouseEnter}>
  Hover me
</button>

// ❌ INCORRECT - lowercase
<button onclick={handleClick}>  // Warning!
  Click me
</button>

// ❌ INCORRECT - incorrect camelCase
<button onmouseenter={handleMouseEnter}>  // Warning!
  Hover me
</button>

Common correct event names: onClick, onChange, onSubmit, onKeyDown, onMouseEnter, onMouseLeave, onFocus, onBlur.

3Filter non-DOM props when spreading to DOM elements

If you're using prop spreading ({...props}) on a DOM element, destructure props first to separate DOM-safe props from custom ones:

jsx
// ❌ PROBLEMATIC - spreads all props including custom event handlers
function MyComponent(props) {
  return <div {...props} />;
}

// ✅ SOLUTION - filter out non-DOM props
function MyComponent({ onSpecialEvent, customData, ...domProps }) {
  // domProps contains only props safe for DOM elements
  return <div {...domProps} />;
}

// ✅ ALTERNATIVE - explicitly pass only known DOM props
function MyComponent({ className, style, onClick, children }) {
  return (
    <div className={className} style={style} onClick={onClick}>
      {children}
    </div>
  );
}
4Use data-* attributes for custom DOM data instead of custom props

If you need to attach custom data to DOM elements, use the standard data-* attribute format instead of custom props:

jsx
// ❌ AVOID - custom prop on DOM element
<div onSpecialEvent={handler}>
  Content
</div>

// ✅ USE - data attribute with manual event handling
<div data-event-type="special" onClick={handleSpecialClick}>
  Content
</div>

// In your event handler:
function handleSpecialClick(event) {
  if (event.target.dataset.eventType === 'special') {
    // Handle special event
  }
}

This follows HTML5 conventions and avoids React warnings.

5Ensure custom components start with uppercase letters

React treats lowercase tags as DOM elements and uppercase tags as custom components. If you're getting this warning on a component you wrote, check its naming:

jsx
// ✅ CORRECT - uppercase for custom components
function MyButton({ onSpecialClick }) {
  return <button onClick={onSpecialClick}>Click</button>;
}
// Usage: <MyButton onSpecialClick={handler} /> - No warning!

// ❌ INCORRECT - lowercase treated as DOM element
function mybutton({ onSpecialClick }) {
  return <button onClick={onSpecialClick}>Click</button>;
}
// Usage: <mybutton onSpecialClick={handler} /> - Warning!

Custom React components must start with uppercase letters or use React.createElement() directly.

6Use refs for custom event handling on DOM elements

If you need to attach non-standard event listeners to DOM elements, use refs with useEffect:

jsx
import { useRef, useEffect } from 'react';

function MyComponent() {
  const divRef = useRef();

  useEffect(() => {
    const handleSpecialEvent = (event) => {
      console.log('Special event fired', event);
    };

    const element = divRef.current;
    element.addEventListener('special-event', handleSpecialEvent);

    // Cleanup
    return () => {
      element.removeEventListener('special-event', handleSpecialEvent);
    };
  }, []);

  return <div ref={divRef}>Content</div>;
}

This approach gives you full control over event handling without triggering React warnings.

Advanced notes

React's synthetic event system provides cross-browser compatibility and performance optimizations. The whitelist of known DOM attributes helps React optimize rendering and avoid unnecessary re-renders. In production builds, this warning is stripped out, but the unknown props are still attached to DOM nodes, which can cause:

1. Performance issues: Extra properties on DOM nodes increase memory usage
2. Unexpected behavior: Some props might conflict with future DOM APIs
3. Accessibility problems: Screen readers might misinterpret custom props

For library authors, consider using TypeScript to catch these issues at compile time, or use runtime prop-type validation. When building higher-order components or render props patterns, always filter props before passing them to DOM elements.

Frequently asked questions

What does "Warning: Unknown event handler property `on`" mean?
React maintains a whitelist of known DOM attributes and event handlers. ) that React doesn't recognize, it assumes you're trying to attach an event handler but can't find a corresponding event in its synthetic event system. React warns you because the handler won't work as expected, and the property will be attached directly to the DOM node, which can cause performance issues and unexpected behavior.
How do I fix "Warning: Unknown event handler property `on`"?
This warning occurs when React encounters an event handler property starting with "on" that it doesn't recognize as a valid DOM event. This typically happens due to typos in event names, using custom event handlers on DOM elements, or incorrectly spreading props to native HTML elements.
What causes "Warning: Unknown event handler property `on`"?
Misspelling standard React event handlers (e.g., "onclick" instead of "onClick", "onMouseenter" instead of "onMouseEnter") Spreading props containing custom event handlers to DOM elements without filtering Using custom event handler names on native DOM elements (e.g., onSpecialEvent on a <div>)
Is the "Warning: Unknown event handler property `on`" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading