React Synthetic Events Explained

A React synthetic event is the event object React passes to your handlers. It wraps the browser's native event and smooths over differences between browsers, so the same handler behaves the same way everywhere. It is also called the React event object.

Why React wraps events

Browsers disagree on small details of event behavior, and React normalizes those differences. React makes onBlur and onFocus bubble even though the native events do not, and it makes onLoad and onError bubble where the browser does not. Some React events also map to a different native event underneath, like onMouseLeave mapping to the native mouseout. You write one handler and React handles the rest.

What you can read on it

The synthetic event implements the standard Event properties. You can read e.target for the element the event started on, e.currentTarget for the element the current handler is attached to, and e.type for the event name.

App.jsx

<button onClick={(e) => console.log(e.type, e.target.tagName)}>Click</button>

Clicking the button logs the type click and the target tag BUTTON. The properties behave like the native ones, with React applying its own normalization where browsers differ. Standard properties like bubbles, cancelable, and timeStamp are also present, so you rarely need to leave the synthetic event.

Methods that work

e.preventDefault() cancels the browser's default action, and e.stopPropagation() stops the event from bubbling. The helper methods isDefaultPrevented and isPropagationStopped report whether either was already called, which is useful in shared handlers. The names match the native methods, so the learning curve is small.

Events are no longer pooled

Older React reused one event object across handlers, which meant you had to call e.persist() to keep a value after the handler returned. React 17 removed that pooling, so modern React does not reuse the object and you can keep a reference to it freely. The persist method still exists but is not used with React DOM.

Use nativeEvent when you must

Most of the time the synthetic event is all you need. If you need a browser-specific property, read it from e.nativeEvent, which is the underlying native event. A common case is checking a browser-only property or handing the event to a library that expects a raw event. The exact mapping between React events and native events is not part of the public API, so treat nativeEvent as an escape hatch.

What to learn next

How the event moves through the tree is covered in event bubbling and capturing, and stopping propagation uses the synthetic event's own method.