React Reference ยท Props and Attributes
React SyntheticEvent object
Reference for the React SyntheticEvent passed to event handlers: target vs currentTarget, nativeEvent, preventDefault, stopPropagation and event pooling.
Every event handler receives a SyntheticEvent: a wrapper that React builds around the browser's native event. It has the same interface as the native event (type, target, preventDefault(), stopPropagation() and so on), but its behavior is the same in every browser. Specific events extend it, so a click handler gets clientX and button, a keyboard handler gets key and code, and an input handler gets properties for the target input.
Since React 17 events are no longer pooled, so you can read an event after an await without calling persist().
function handleClick(event) { console.log(event.type, event.target, event.currentTarget); }
Try it
Reading an event after an await is safe with current React.
Syntax
function handler(event: React.SyntheticEvent) { ... }
| Property or method | Description |
|---|---|
type |
The event name, such as "click" (without the on). |
target |
The deepest element that triggered the event. |
currentTarget |
The element whose handler is running now (the one with the prop). |
nativeEvent |
The underlying browser event object. |
bubbles, cancelable, eventPhase, isTrusted, timeStamp |
Same meaning as on native events. |
defaultPrevented, isDefaultPrevented() |
Whether preventDefault() was called. |
preventDefault() |
Cancels the browser's default action (link navigation, form submit). |
stopPropagation(), isPropagationStopped() |
Stops the event from reaching other React handlers on ancestors. |
persist() |
Does nothing since React 17; kept for compatibility. |
Usage notes
targetis not always the element you wrote the handler on. Clicking a<span>inside a button givestarget= the span,currentTarget= the button. UsecurrentTargetwhen you need the element with the handler.- Typing
target. In TypeScript,event.targetis a plainEventTarget; useevent.currentTarget(typed as the element) orChangeEvent<HTMLInputElement>to get.value. - Do not store events in state. Copy the values you need (
const x = event.clientX) instead. currentTargetis only valid during the handler. After anawait,event.currentTargetisnull, because React clears it when the dispatch ends. Copy it to a variable first.- Reaching the native event with
nativeEventis rarely needed; use it for properties React does not expose. - Different from DOM listeners. React attaches one listener per event type to the root, and dispatches to your handlers, so ordering relative to
addEventListenercalls on inner nodes can surprise you.