Understanding React Synthetic Events: Architecture, Code, and Common Pitfalls

Introduction

React synthetic events are objects that emulate native DOM events, following the W3C spec, providing cross‑browser compatibility and the same interface as native events.

Official React description (image showing synthetic event object and nativeEvent).

React Event System Architecture

Core Code – Registration and Execution

1. Registration

function enqueuePutListener(inst, registrationName, listener, transaction) {
    // ...
    var isDocumentFragment = containerInfo._node && containerInfo._node.nodeType === DOC_FRAGMENT_TYPE;
    // 1. Find document
    var doc = isDocumentFragment ? containerInfo._node : containerInfo._ownerDocument;
    // 2. Register event on document
    // 3. listenTo(registrationName, doc);
    // Store event in transaction queue
}

React normalizes event handling across browsers, so developers do not need to consider browser differences.

function listen(target, eventType, callback) {
    if (target.addEventListener) {
        // Attach native event to the target (usually document)
        target.addEventListener(eventType, callback, false);
        // ...
    } else if (target.attachEvent) {
        target.attachEvent('on' + eventType, callback);
        // ...
    }
}

2. Execution

Event dispatch (synthetic event bubbling)

function handleTopLevelImpl(bookKeeping) {
    // 1. Find the DOM node that triggered the event and its React component
    var nativeEventTarget = getEventTarget(bookKeeping.nativeEvent);
    var targetInst = ReactDOMComponentTree.getClosestInstanceFromNode(nativeEventTarget);

    // 2. Build the ancestors array (bubbling order)
    var ancestor = targetInst;
    do {
        bookKeeping.ancestors.push(ancestor);
        ancestor = ancestor && findParent(ancestor);
    } while (ancestor);

    // Invoke listeners in bubbling order
    for (var i = 0; i < bookKeeping.ancestors.length; i++) {
        targetInst = bookKeeping.ancestors[i];
        ReactEventListener._handleTopLevel(
            bookKeeping.topLevelType,
            targetInst,
            bookKeeping.nativeEvent,
            getEventTarget(bookKeeping.nativeEvent)
        );
    }
}

handleTopLevel – creates synthetic event and processes it via EventPluginHub

// 1. Register plugins
ReactInjection.EventPluginHub.injectEventPluginsByName({
    // ...different plugins
});

// 2. Enqueue events into the pool
EventPluginHub.enqueueEvents(events);

// 3. Process the queued events
EventPluginHub.processEventQueue(false);

Demo: Mixing Synthetic and Native Events

A small demo shows the execution order differences when React synthetic events and native DOM events are used together. (images of demo and result).

Why Synthetic Events Matter

Unified management through the document.

Cross‑browser compatibility.

Reduced performance cost by avoiding frequent creation and destruction of native listeners.

Leverages bubbling from the document.

Known Issues with Synthetic Events

1. Interaction with native events

Preventing native event bubbling also stops the React synthetic event.

Preventing synthetic event bubbling does not affect native listeners.

2. Event pool clears properties after all handlers run

Use e.persist() to keep the event object from being cleared.

React 17 removes the event pool, eliminating this issue.

3. stopPropagation may fail when different React versions are nested

References

https://react.docschina.org/

https://github.com/facebook/react/

React 17 release article (blog link)