The Event System

This page sits between the user and setState. It explains why a click produces a SyncLane update, and how React finds your handler without any per-element listeners.

1. Setup: listenToAllSupportedEvents

createRoot (and hydrateRoot) call listenToAllSupportedEvents(rootContainerElement) once per container.¹

export function listenToAllSupportedEvents(rootContainerElement) {
  if (!rootContainerElement[listeningMarker]) {
    rootContainerElement[listeningMarker] = true;
    allNativeEvents.forEach(domEventName => {
      if (domEventName !== 'selectionchange') {
        if (!nonDelegatedEvents.has(domEventName)) {
          listenToNativeEvent(domEventName, false, rootContainerElement); // bubble
        }
        listenToNativeEvent(domEventName, true, rootContainerElement);    // capture
      }
    });
    // 'selectionchange' only fires on document → listen there once
  }
}

(simplified)²

• allNativeEvents is filled at module load. SimpleEventPlugin.registerEvents() and the polyfill plugins (EnterLeave, Change, Select, BeforeInput) register their event names.³ registerSimpleEvents builds the domEventName → reactName map, click → onClick, plus special cases. Note focusin → onFocus and focusout → onBlur: React's onFocus bubbles because it's really focusin.⁴
• nonDelegatedEvents (scroll, scrollend, load, cancel, close, invalid, toggle, beforetoggle and all media events) don't bubble in the DOM. They get only a capture listener on the root here. React also attaches them directly to the element when it creates a host instance that needs them (listenToNonDelegatedEvent).⁵
• addTrappedEventListener creates the actual listener via createEventListenerWrapperWithPriority. It marks touchstart, touchmove and wheel as {passive: true} where supported, so React never blocks scrolling.⁶

Why delegate at all? A table with 10,000 rows would otherwise need 10,000 listeners, re-attached on every mount. With delegation, attaching an onClick costs nothing beyond storing the prop, and handlers can change every render without any add/removeEventListener churn. The cost is an extra walk up the fiber tree on each event.

2. Priority is baked into the listener

export function createEventListenerWrapperWithPriority(targetContainer, domEventName, eventSystemFlags) {
  const eventPriority = getEventPriority(domEventName);
  let listenerWrapper;
  switch (eventPriority) {
    case DiscreteEventPriority:   listenerWrapper = dispatchDiscreteEvent; break;
    case ContinuousEventPriority: listenerWrapper = dispatchContinuousEvent; break;
    default:                      listenerWrapper = dispatchEvent; break;
  }
  return listenerWrapper.bind(null, domEventName, eventSystemFlags, targetContainer);
}

⁸

getEventPriority is a big switch. click, keydown, input, mousedown, pointerup, focusin and similar are Discrete. mousemove, pointermove, scroll, wheel, drag and mouseenter/leave are Continuous. message maps from the current Scheduler priority. Everything else is Default.⁹

function dispatchDiscreteEvent(domEventName, eventSystemFlags, container, nativeEvent) {
  const prevTransition = ReactSharedInternals.T;
  ReactSharedInternals.T = null;                       // a click is never inside a transition
  const previousPriority = getCurrentUpdatePriority();
  try {
    setCurrentUpdatePriority(DiscreteEventPriority);   // ReactDOMSharedInternals.p = SyncLane
    dispatchEvent(domEventName, eventSystemFlags, container, nativeEvent);
  } finally {
    setCurrentUpdatePriority(previousPriority);
    ReactSharedInternals.T = prevTransition;
  }
}

¹⁰

This is the link to setState. requestUpdateLane → resolveUpdatePriority() reads ReactDOMSharedInternals.p, finds DiscreteEventPriority (= SyncLane), and every setState in your click handler gets SyncLane.¹¹ dispatchContinuousEvent does the same thing with ContinuousEventPriority (= InputContinuousLane).¹² The priority is a dynamic scope: it's set around the call and restored afterwards, the same pattern flushSync and startTransition use.

3. dispatchEvent: from DOM node to fiber

dispatchEvent first calls findInstanceBlockingEvent(nativeEvent). That gets the event target, then calls findInstanceBlockingTarget, which uses getClosestInstanceFromNode(target) to get the fiber.¹³¹⁴ During hydration the target may sit inside a dehydrated Suspense/Activity boundary. In that case the event is "blocked": continuous events are queued for replay, and discrete events try to hydrate synchronously first. In the normal case it's not blocked, and dispatchEventForPluginEventSystem is called with the target fiber.

How a DOM node knows its fiber: when completeWork creates a host instance, createInstance calls precacheFiberNode(fiber, domElement) and updateFiberProps(domElement, props).¹⁵ These write two expando properties with a per-load random suffix: '__reactFiber$' + randomKey and '__reactProps$' + randomKey.¹⁶¹⁷¹⁸ commitUpdate refreshes __reactProps$ on every update, so the props there are always the latest committed props.¹⁹

getClosestInstanceFromNode reads node[internalInstanceKey]. If the target isn't React-owned (innerHTML content, a third-party widget), it walks parentNode until it finds one.²⁰ (enableInternalInstanceMap, which uses a WeakMap instead of expandos, is false in this release.)

dispatchEventForPluginEventSystem then handles portals and nested roots. It walks up to find the HostRoot/HostPortal whose container matches the container that received the event, so an event isn't handled twice by nested roots. Finally it calls batchedUpdates(() => dispatchEventsForPlugins(...)).²¹ In 19.x OSS the DOM-level batchedUpdates mostly exists to run finishEventHandler afterwards. That restores controlled inputs, flushing sync work first if a controlled component needs it.²²

4. extractEvents and accumulateSinglePhaseListeners

dispatchEventsForPlugins creates an empty dispatchQueue, calls extractEvents, and then processDispatchQueue.²³ extractEvents always runs SimpleEventPlugin.extractEvents. For the bubble phase it also runs the polyfill plugins: EnterLeave (synthesises onMouseEnter from mouseover/mouseout), Change, Select, BeforeInput, and FormAction.²⁴

SimpleEventPlugin.extractEvents maps click → onClick and picks the synthetic event constructor (SyntheticMouseEvent for click). It works out inCapturePhase from the listener flags, then collects listeners:²⁵

const listeners = accumulateSinglePhaseListeners(
  targetInst, reactName /* 'onClick' */, nativeEvent.type,
  inCapturePhase, accumulateTargetOnly /* true for non-bubbling scroll */, nativeEvent,
);
if (listeners.length > 0) {
  const event = new SyntheticEventCtor(reactName, reactEventType, null, nativeEvent, nativeEventTarget);
  dispatchQueue.push({ event, listeners });
}

export function accumulateSinglePhaseListeners(targetFiber, reactName, nativeEventType,
                                               inCapturePhase, accumulateTargetOnly, nativeEvent) {
  const reactEventName = inCapturePhase ? reactName + 'Capture' : reactName; // onClickCapture
  const listeners = [];
  let instance = targetFiber;
  let lastHostComponent = null;
  while (instance !== null) {
    const { stateNode, tag } = instance;
    if ((tag === HostComponent || tag === HostHoistable || tag === HostSingleton) && stateNode !== null) {
      lastHostComponent = stateNode;
      const listener = getListener(instance, reactEventName);  // stateNode.__reactProps$[...].onClick
      if (listener != null) listeners.push({ instance, listener, currentTarget: lastHostComponent });
    }
    if (accumulateTargetOnly) break;
    instance = instance.return;
  }
  return listeners;   // ordered target → root
}

(simplified, createEventHandle/Scope API branches dropped)²⁶

What matters:

• It walks the fiber tree, not the DOM tree. That's why events bubble through portals to their React parent, even when the portal's DOM lives in document.body. instance.return follows the component hierarchy.
• Only host fibers contribute. <MyButton onClick> on a function component is just a prop. Only when it reaches a <button> (HostComponent) is onClick read, and it's read from the DOM node's current props (getListener → getFiberCurrentPropsFromNode), not from fiber.memoizedProps.²⁷ Since commitUpdate updates __reactProps$ during commit, handlers are always the latest committed ones, with no listener re-binding.
• getListener returns null for mouse events on disabled interactive elements (button, input, select, textarea). That matches browser behaviour across all of them.²⁷
• One SyntheticEvent per dispatch, shared by all listeners in the path. Its currentTarget is set per listener.

5. SyntheticEvent and processDispatchQueue

createSyntheticEvent(Interface) returns a constructor that copies the interface's fields from the native event (normalising cross-browser quirks) and stores nativeEvent, target, type and _reactName. It implements preventDefault()/stopPropagation() by calling the native method and flipping isDefaultPrevented/isPropagationStopped.²⁸ persist() is a no-op and isPersistent() always returns true. Event pooling was removed in React 17, and the methods are kept only for compatibility.²⁸

function processDispatchQueueItemsInOrder(event, dispatchListeners, inCapturePhase) {
  let previousInstance;
  if (inCapturePhase) {
    for (let i = dispatchListeners.length - 1; i >= 0; i--) { /* root → target */ }
  } else {
    for (let i = 0; i < dispatchListeners.length; i++) {      /* target → root */
      const { instance, currentTarget, listener } = dispatchListeners[i];
      if (instance !== previousInstance && event.isPropagationStopped()) return;
      executeDispatch(event, listener, currentTarget);         // try { listener(event) } catch → reportGlobalError
      previousInstance = instance;
    }
  }
}

(simplified)²⁹³⁰³¹

Capture and bubble are simulated in one list by iterating it backwards or forwards. The capture-phase native listener collects onClickCapture handlers and runs them root→target. The bubble-phase native listener collects onClick and runs them target→root. An error thrown in one handler is reported via reportGlobalError (and window.onerror). It doesn't stop the other handlers.

6. End to end: a click becomes pixels

sequenceDiagram
  participant U as User
  participant B as Browser
  participant R as Root container listener
  participant P as Plugin system
  participant H as Your onClick
  participant S as Root scheduler
  U->>B: click <button>
  B->>R: native 'click' (capture listener: onClickCapture handlers)
  B->>R: native 'click' (bubble listener)
  R->>R: dispatchDiscreteEvent: priority = Discrete (SyncLane), T = null
  R->>P: dispatchEvent → getClosestInstanceFromNode(target) → fiber
  P->>P: SimpleEventPlugin: accumulateSinglePhaseListeners (fiber.return walk)
  P->>H: processDispatchQueue → listener(syntheticEvent)
  H->>S: setCount() → requestUpdateLane = SyncLane → enqueue → ensureRootIsScheduled
  S-->>S: queueMicrotask (once)
  R->>R: restore priority, finishEventHandler
  Note over B,S: listener returns, JS stack empty → microtask checkpoint
  S->>S: processRootScheduleInMicrotask → flushSyncWorkAcrossRoots → performSyncWorkOnRoot
  S->>B: render + commit (DOM mutated, layout effects run)
  B->>U: style/layout/paint the new frame

Because the update is SyncLane, scheduleTaskForRootDuringMicrotask doesn't create a Scheduler task. The render runs straight from flushSyncWorkAcrossRoots_impl inside the microtask.³²³³ Microtasks run before the browser gets a chance to render a frame, so the DOM is updated before the next paint. Passive effects (useEffect) from a discrete update are also flushed synchronously at the end of the commit rather than later³⁴, so the UI is consistent before any further input (see Commit Phase). The full trace with every function is in setState Walkthrough.

With the React Compiler

Unchanged. The event system lives in react-dom-bindings and runs no component code apart from your handlers. What the compiler changes is handler identity. Without it, onClick={() => setCount(c => c + 1)} is a new function every render, which is harmless for DOM elements: React just reads the latest one from __reactProps$, and attribute diffing treats event props specially. But it breaks memo on child components that receive the handler. The compiler caches such closures in its memo cache (keyed on the values they capture), so memo children and effect deps see stable functions. See React Compiler and With vs Without Compiler.

Summary

React never puts your onClick on the button. createRoot installs one capture and one bubble listener per native event type on the root container, each wrapped with a priority. On a click, React finds the target's fiber through a hidden key on the DOM node, walks fiber.return collecting handlers, and calls them with one shared SyntheticEvent. The priority scope around that call is the link to setState: every setState in the handler gets SyncLane and is rendered and committed in a microtask before paint. Next, the compiler, which changes handler identity but not this pipeline.

Key takeaways

• listenToAllSupportedEvents: runs once per container; nonDelegatedEvents get only a capture listener here and are also attached to the element.
• createEventListenerWrapperWithPriority: picks the wrapper from getEventPriority, so priority is baked into the listener.
• dispatchDiscreteEvent: sets DiscreteEventPriority (= SyncLane) and clears the transition around the dispatch, then restores both.
• __reactFiber$ / __reactProps$: expandos written by createInstance and refreshed by commitUpdate; they map a DOM target to its fiber and hold the latest committed props.
• accumulateSinglePhaseListeners: walks the fiber tree, not the DOM, so events bubble through portals; only host fibers contribute.
• processDispatchQueue: runs one list backwards for capture and forwards for bubble; a throwing handler doesn't stop the others.
• SyntheticEvent: one per dispatch, shared by all listeners; persist() is a no-op since pooling was removed.
• Sync flush: a SyncLane update gets no Scheduler task and renders in a microtask, so the DOM changes before the next paint.

← Prev · Index · Next →