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.
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.
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.
// Example of problematic code that might trigger the warning
function MyComponent({ onSpecialClick, ...props }) {
return <div onSpecialClick={onSpecialClick} {...props} />;
}Review all event handler props in the component. Standard React events use camelCase:
// ✅ 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.
If you're using prop spreading ({...props}) on a DOM element, destructure props first to separate DOM-safe props from custom ones:
// ❌ 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>
);
}If you need to attach custom data to DOM elements, use the standard data-* attribute format instead of custom props:
// ❌ 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.
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:
// ✅ 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.
If you need to attach non-standard event listeners to DOM elements, use refs with useEffect:
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.
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.
React.FC expects children prop to be defined
React.FC no longer includes implicit children prop
Warning: You provided a `selected` prop to a form field without an `onChange` handler
You provided a 'selected' prop without an onChange handler
Failed to load source map from suspense chunk
How to fix "Failed to load source map from suspense chunk" in React
Prop spreading could cause security issues
Prop spreading could cause security issues
React Hook useCallback has a missing dependency: 'variable'. Either include it or remove the dependency array react-hooks/exhaustive-deps
React Hook useCallback has a missing dependency