Use when handling user interactions, typing event handlers with TypeScript, working with form inputs, or implementing keyboard/mouse interactions. Prevents the common mistake of using incorrect event types or accessing pooled event properties asynchronously. Covers synthetic events, TypeScript event annotations, form/keyboard/mouse events, stopPropagation, preventDefault, delegation. Keywords: SyntheticEvent, onClick, onChange, event handler, preventDefault, onClick, onChange, keyboard event, form event, event types TypeScript, handle click..
Use when handling user interactions, typing event handlers with TypeScript, working with form inputs, or implementing keyboard/mouse interactions. Prevents the common mistake of using incorrect event types or accessing pooled event properties asynchronously. Covers synthetic events, TypeScript event annotations, form/keyboard/mouse events, stopPropagation, preventDefault, delegation. Keywords: SyntheticEvent, onClick, onChange, event handler, preventDefault, onClick, onChange, keyboard event, form event, event types TypeScript, handle click..
license
MIT
compatibility
Designed for Claude Code. Requires React 18.x or 19.x with TypeScript.
metadata
{"author":"OpenAEC-Foundation","version":"1.0"}
react-syntax-events
Quick Reference
Synthetic Event System
React wraps all native browser events in SyntheticEvent objects. These wrappers normalize cross-browser differences and provide a consistent API.
Concept
Detail
Wrapper
Every handler receives a SyntheticEvent, NOT a native Event
Delegation
React attaches ONE listener to the root container, NOT to individual DOM nodes
Pooling
React 17+ does NOT pool events -- accessing e in async callbacks is safe
Native access
Use e.nativeEvent to access the underlying browser event
The generic parameter T specifies the element the handler is attached to. ALWAYS provide it for correct e.currentTarget typing.
Critical Warnings
NEVER use onKeyPress -- it is deprecated. ALWAYS use onKeyDown or onKeyUp instead.
NEVER type event handlers as (e: any) => void -- ALWAYS use the specific React event type with the correct element generic.
NEVER call e.stopPropagation() as a default habit -- it breaks parent listeners, analytics tools, and modal close handlers. ONLY use it when you have a specific reason.
ALWAYS call e.preventDefault() in onSubmit handlers to prevent full page reload.
ALWAYS provide the element generic parameter (e.g., <HTMLInputElement>) -- without it, e.currentTarget is typed as HTMLElement and you lose access to element-specific properties like .value.
NEVER read e.currentTarget inside async/await or setTimeout -- currentTarget is set to null after the event handler returns. Extract the value synchronously first.
NEVER use .bind(this, arg) in function components -- it creates a new function reference every render just like arrow functions, but with worse readability.
stopPropagation vs preventDefault
Method
Purpose
Use When
e.preventDefault()
Prevents the browser default action
Form submit, link navigation, drag default behavior
onMouseEnter / onMouseLeave do NOT bubble -- they fire only for the exact element, not its children. Use these for hover states. Use onMouseOver / onMouseOut when you need bubbling behavior.
Keyboard Events
Prop
Fires When
onKeyDown
Key pressed down (repeats while held)
onKeyUp
Key released
NEVER use onKeyPress -- it is deprecated and does not fire for non-character keys (Escape, Arrow keys, etc.).
Key Detection
ALWAYS use e.key (string value) instead of e.keyCode (deprecated numeric code):
React's onFocus and onBlur bubble, unlike the native focus/blur events. This matches the native focusin/focusout behavior.
relatedTarget
const handleBlur = (e: React.FocusEvent<HTMLInputElement>): void => {
if (e.relatedTarget === null) {
// Focus left the document entirelyvalidateField();
}
};
e.relatedTarget is the element that received (onBlur) or lost (onFocus) focus. It is null when focus moves outside the document.
React 18 vs React 19 Differences
Feature
React 18
React 19
Event delegation
Root container
Root container (unchanged)
Event pooling
Removed (since 17)
Removed
ref as prop
Use forwardRef for function components
ref is a regular prop -- no forwardRef needed
Form actions
Not available
<form action={fn}> with useActionState
In React 19, forms can use the action prop directly. For new projects on React 19, prefer action + useActionState over manual onSubmit + preventDefault for form submissions with server mutations.
