React's event system

One click, followed into react-dom

When you write onClick, it looks as if React puts a click listener on that button. The Responding to events lesson said it doesn't. This shop proves it. The spy.js tab records every addEventListener call from the moment it loads. Press Count the listeners.

1import { useState } from "react";2import { listenersOn } from "./spy.js";3 4export default function App() {5  const [cart, setCart] = useState(0);6  const [report, setReport] = useState("");7 8  function countListeners() {9    const root = document.getElementById("root");10    const onRoot = listenersOn(root);11    const kinds = new Set(onRoot.map((entry) => entry.type));12    const onButtons = [...document.querySelectorAll("button")].flatMap(listenersOn);13    setReport(`#root: ${onRoot.length} listeners for ${kinds.size} kinds of event. The buttons: ${onButtons.length}.`);14  }15 16  return (17    <>18      <button onClick={() => setCart(cart + 1)}>Add to cart ({cart})</button>19      <button onClick={countListeners}>Count the listeners</button>20      <p>{report}</p>21    </>22  );23}

In spy.js, lines 6 to 10 replace addEventListener on every element with a version that notes the element, the event and the phase (line 8), then adds the listener as usual. App.jsx imports it, and the preview's main.jsx loads App.jsx before it calls createRoot, so the spy is ready when react-dom starts listening. Line 10 of App.jsx collects the listeners on #root, and line 12 those on the two buttons. The page reads #root: 142 listeners for 87 kinds of event. The buttons: 0.

Both buttons have onClick, and neither has a listener. All of react-dom's listeners sit on #root, the element you passed to createRoot: 87 kinds of event, from clicks and keys to scrolls and media events, whether your app uses them or not. A click on the button bubbles up to #root, and react-dom works out from there which of your handlers to call. Using one listener on a parent for events on many children is called event delegation.

Two listeners per event, on the root

The listeners are added by createRoot, near its end, in ReactDOMRoot.js, lines 254 to 258:

const rootContainerElement: Document | Element | DocumentFragment =
  !disableCommentsAsDOMContainers && container.nodeType === COMMENT_NODE
    ? (container.parentNode as any)
    : container;
listenToAllSupportedEvents(rootContainerElement);

Lines 1 to 4 pick the element: your container, or its parent in the rare case where the container is a comment node. Line 5 hands it to listenToAllSupportedEvents:

export function listenToAllSupportedEvents(rootContainerElement: EventTarget) {
  if (!(rootContainerElement as any)[listeningMarker]) {
    (rootContainerElement as any)[listeningMarker] = true;
    allNativeEvents.forEach(domEventName => {
      // We handle selectionchange separately because it
      // doesn't bubble and needs to be on the document.
      if (domEventName !== 'selectionchange') {
        if (!nonDelegatedEvents.has(domEventName)) {
          listenToNativeEvent(domEventName, false, rootContainerElement);
        }
        listenToNativeEvent(domEventName, true, rootContainerElement);
      }
    });
    const ownerDocument =
      (rootContainerElement as any).nodeType === DOCUMENT_NODE
        ? rootContainerElement
        : (rootContainerElement as any).ownerDocument;
    // $FlowFixMe[invalid-compare]
    if (ownerDocument !== null) {
      // The selectionchange event also needs deduplication
      // but it is attached to the document.
      if (!(ownerDocument as any)[listeningMarker]) {
        (ownerDocument as any)[listeningMarker] = true;
        listenToNativeEvent('selectionchange', false, ownerDocument);
      }
    }
  }
}

1. Lines 2 and 3: a hidden marker property, so a second call for the same element adds nothing.
2. Line 4 loops over allNativeEvents: every browser event that any event plugin registered when react-dom loaded.
3. Line 11 adds a capture listener for each event, and line 9 a bubble listener, except for the events in nonDelegatedEvents.
4. Lines 14 to 25 put one selectionchange listener on document, the only place the browser fires it.

That explains the count: 87 kinds of event, each with a capture listener, and 55 of them with a bubble listener too. nonDelegatedEvents holds 32 events that don't bubble in the browser, like scroll, load and the media events. A root can still hear them in the capture phase, and when an element has onScroll, React adds a scroll listener to that element itself (ReactDOMComponent.js). This table reads the same spy for a few events:

1import { listenersOn } from "./spy.js";2 3const kinds = ["click", "keydown", "input", "focusin", "mouseover", "scroll", "load", "focus", "mouseenter"];4 5export default function App() {6  const onRoot = listenersOn(document.getElementById("root"));7  const has = (type, capture) => onRoot.some((entry) => entry.type === type && entry.capture === capture);8 9  return (10    <table>11      <thead>12        <tr><th>Event</th><th>Capture</th><th>Bubble</th></tr>13      </thead>14      <tbody>15        {kinds.map((type) => (16          <tr key={type}>17            <td>{type}</td>18            <td>{has(type, true) ? "yes" : "no"}</td>19            <td>{has(type, false) ? "yes" : "no"}</td>20          </tr>21        ))}22      </tbody>23    </table>24  );25}

Line 7 checks the recorded listeners on #root for one event and one phase. click, keydown, input, focusin and mouseover say yes and yes. scroll and load say yes and no. focus and mouseenter say no and no: React builds onFocus from focusin, and onMouseEnter from mouseover and mouseout, as the plugins section shows.

React 17 moved these listeners from document to the root, so that two React apps, or two versions of React, can share a page. A few other things changed with it. How to read the table: each row asks one question of React 16 and of React 17 and later.

From the browser's event to your handler

What does each of those 142 listeners run? Each one is built by createEventListenerWrapperWithPriority, in ReactDOMEventListener.js, lines 94 to 119:

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

1. Line 6 asks getEventPriority how urgent this kind of event is. The priorities section reads it.
2. Lines 8 to 19 pick a wrapper for that priority. For a click, it's dispatchDiscreteEvent.
3. Lines 20 to 25 bind the wrapper to the event's name, some flags (one of them says capture or bubble), and the container. The result is the function addEventListener receives.

function dispatchDiscreteEvent(
  domEventName: DOMEventName,
  eventSystemFlags: EventSystemFlags,
  container: EventTarget,
  nativeEvent: AnyNativeEvent,
) {
  const prevTransition = ReactSharedInternals.T;
  ReactSharedInternals.T = null;
  const previousPriority = getCurrentUpdatePriority();
  try {
    setCurrentUpdatePriority(DiscreteEventPriority);
    dispatchEvent(domEventName, eventSystemFlags, container, nativeEvent);
  } finally {
    setCurrentUpdatePriority(previousPriority);
    ReactSharedInternals.T = prevTransition;
  }
}

Lines 7 and 8 set aside any transition that is running, so updates in your handler aren't treated as part of it. Line 11 sets the update priority to discrete while line 12 runs dispatchEvent, and lines 13 to 16 put both back. (See the file.) dispatchEvent finds the fiber of the element that was clicked with getClosestInstanceFromNode, which reads the __reactFiber$ key the fiber lesson found on every DOM element react-dom creates. Then dispatchEventForPluginEventSystem ends with this, at lines 694 to 702 of DOMPluginEventSystem.js:

batchedUpdates(() =>
  dispatchEventsForPlugins(
    domEventName,
    eventSystemFlags,
    nativeEvent,
    ancestorInst,
    targetContainer,
  ),
);

batchedUpdates marks the time while your handlers run, so React renders their updates together afterwards. Inside it runs dispatchEventsForPlugins:

function dispatchEventsForPlugins(
  domEventName: DOMEventName,
  eventSystemFlags: EventSystemFlags,
  nativeEvent: AnyNativeEvent,
  targetInst: null | Fiber,
  targetContainer: EventTarget,
): void {
  const nativeEventTarget = getEventTarget(nativeEvent);
  const dispatchQueue: DispatchQueue = [];
  extractEvents(
    dispatchQueue,
    domEventName,
    targetInst,
    nativeEvent,
    nativeEventTarget,
    eventSystemFlags,
    targetContainer,
  );
  processDispatchQueue(dispatchQueue, eventSystemFlags);
}

Line 8 gets the element the event happened on. Line 9 makes an empty dispatch queue. Lines 10 to 18 let the plugins fill it with pairs of a React event and the handlers that want it. Line 19 calls those handlers. The next three sections open each step.

Before that, step through one click on a page with native listeners too. The order example further down logs the same lines; here you see which listener runs each one, and what react-dom calls inside its own two.

Plugins turn browser events into React events

React events don't match the browser's one for one. Event plugins do the matching. When react-dom loads, each registers the React props it supports and the browser events it needs (DOMPluginEventSystem.js, lines 93 to 100). Then extractEvents asks them, in order:

SimpleEventPlugin.extractEvents(
  dispatchQueue,
  domEventName,
  targetInst,
  nativeEvent,
  nativeEventTarget,
  eventSystemFlags,
  targetContainer,
);
const shouldProcessPolyfillPlugins =
  (eventSystemFlags & SHOULD_NOT_PROCESS_POLYFILL_EVENT_PLUGINS) === 0;
// ... (comments left out)
if (shouldProcessPolyfillPlugins) {
  EnterLeaveEventPlugin.extractEvents(
    dispatchQueue,
    domEventName,
    targetInst,
    nativeEvent,
    nativeEventTarget,
    eventSystemFlags,
    targetContainer,
  );

Lines 1 to 9: SimpleEventPlugin always goes first. Lines 10, 11 and 13: the other plugins run only when this isn't the capture listener, so they see each event once. EnterLeaveEventPlugin is on line 14, and ChangeEventPlugin, SelectEventPlugin, BeforeInputEventPlugin and FormActionEventPlugin follow it the same way. Here is the simple plugin's work, in SimpleEventPlugin.js:

const reactName = topLevelEventsToReactNames.get(domEventName);
if (reactName === undefined) {
  return;
}
let SyntheticEventCtor = SyntheticEvent;
let reactEventType: string = domEventName;
switch (domEventName) {
// ... (the switch that picks the event's class for each kind of event left out)
const inCapturePhase = (eventSystemFlags & IS_CAPTURE_PHASE) !== 0;
// ... (the onScroll rule and an experimental branch left out)
const listeners = accumulateSinglePhaseListeners(
  targetInst,
  reactName,
  nativeEvent.type,
  inCapturePhase,
  accumulateTargetOnly,
  nativeEvent,
);
if (listeners.length > 0) {
  // Intentionally create event lazily.
  const event: ReactSyntheticEvent = new SyntheticEventCtor(
    reactName,
    reactEventType,
    null,
    nativeEvent,
    nativeEventTarget,
  );
  dispatchQueue.push({event, listeners});
}

1. Lines 1 to 4 look up the React name for the browser's: click becomes onClick, focusin becomes onFocus. An event with no simple name stops here.
2. Lines 5 to 7 start choosing the event's class, such as a mouse or keyboard event, by the event's name.
3. Lines 11 to 18 collect the handlers, as the next section shows. Line 15 says which phase this listener is for.
4. Lines 19 to 29: only if someone listens, make one SyntheticEvent and add it with its handlers to the queue. A click nobody handles makes no event object at all.

ChangeEventPlugin shows why plugins exist. It registers onChange with eight browser events, in ChangeEventPlugin.js, lines 35 to 46, and picks the right one for each kind of element, at lines 283 to 287:

function registerEvents() {
  registerTwoPhaseEvent('onChange', [
    'change',
    'click',
    'focusin',
    'focusout',
    'input',
    'keydown',
    'keyup',
    'selectionchange',
  ]);
}

if (shouldUseChangeEvent(targetNode)) {
  getTargetInstFunc = getTargetInstForChangeEvent;
} else if (isTextInputElement(targetNode as any as HTMLElement)) {
  if (isInputEventSupported) {
    getTargetInstFunc = getTargetInstForInputOrChangeEvent;

Lines 1 and 2: a select or a file input uses the browser's change. Lines 3 to 5: a text box uses input, or change, when its value really changed. Type tea in the box below, then press Done.

1import { useEffect, useRef } from "react";2import { note } from "./log.js";3 4export default function App() {5  const box = useRef(null);6 7  useEffect(() => {8    const input = box.current;9    const onNativeChange = () => note(`native change: "${input.value}"`);10    input.addEventListener("change", onNativeChange);11    return () => input.removeEventListener("change", onNativeChange);12  }, []);13 14  function handleChange(e) {15    note(`onChange: "${e.target.value}" (e.type ${e.type}, native ${e.nativeEvent.type})`);16  }17 18  return (19    <>20      <input ref={box} onChange={handleChange} placeholder="Gift note" />21      <button>Done</button>22    </>23  );24}

Line 15 logs once per key, three lines that end with onChange: "tea" (e.type change, native input). React calls the event change, but e.nativeEvent is the browser's input. The browser's own change, heard by lines 9 and 10, fires once, when you leave the box: native change: "tea". React's onChange doesn't fire again then, because the value didn't change since the last key. How to read the table: each row is a React prop, the browser events behind it, and the plugin that makes it.

Collecting handlers by walking the fiber tree

The handlers come from accumulateSinglePhaseListeners, which walks from the target's fiber up to the root:

const captureName = reactName !== null ? reactName + 'Capture' : null;
const reactEventName = inCapturePhase ? captureName : reactName;
let listeners: Array<DispatchListener> = [];

let instance = targetFiber;
let lastHostComponent = null;

// Accumulate all instances and listeners via the target -> root path.
while (instance !== null) {
  const {stateNode, tag} = instance;
  // Handle listeners that are on HostComponents (i.e. <div>)
  if (
    (tag === HostComponent ||
      tag === HostHoistable ||
      tag === HostSingleton) &&
    stateNode !== null
  ) {
    lastHostComponent = stateNode;
    // ... (createEventHandle listeners, an experimental API, left out)
    // Standard React on* listeners, i.e. onClick or onClickCapture
    if (reactEventName !== null) {
      const listener = getListener(instance, reactEventName);
      if (listener != null) {
        listeners.push(
          createDispatchListener(instance, listener, lastHostComponent),
        );
      }
    }
  // ... (scopes, another experimental API, and a rule for onScroll left out)
  instance = instance.return;
}
return listeners;

1. Lines 1 and 2 pick the prop to look for: onClick, or onClickCapture for the capture listener.
2. Lines 9 and 30: a loop that climbs return, the link to the parent fiber, until it passes the root.
3. Lines 12 to 17: only host fibers, the ones for DOM elements, with a DOM node. A component like App is never asked, even if it has a prop called onClick.
4. Lines 21 to 27 read the handler with getListener and push it with its fiber and its DOM element. Line 32 returns the list, target first.

getListener doesn't read the fiber's props. It reads the props stored on the DOM node:

export default function getListener(
  inst: Fiber,
  registrationName: string,
): Function | null {
  const stateNode = inst.stateNode;
  if (stateNode === null) {
    // Work in progress (ex: onload events in incremental mode).
    return null;
  }
  const props = getFiberCurrentPropsFromNode(stateNode);
  if (props === null) {
    // Work in progress.
    return null;
  }
  // $FlowFixMe[invalid-computed-prop]
  const listener = props[registrationName];
  if (shouldPreventMouseEvent(registrationName, inst.type, props)) {
    return null;
  }

  if (listener && typeof listener !== 'function') {
    throw new Error(
      `Expected \`${registrationName}\` listener to be a function, instead got a value of \`${typeof listener}\` type.`,
    );
  }

  return listener;
}

Line 10, getFiberCurrentPropsFromNode, returns the props react-dom saved on the element at the last commit, under a key that starts with __reactProps$. Line 16 picks the handler. Lines 17 to 19 ignore mouse handlers on a disabled button, input, select or textarea, and lines 21 to 25 throw if the prop isn't a function. The list then goes to processDispatchQueueItemsInOrder:

let previousInstance;
if (inCapturePhase) {
  for (let i = dispatchListeners.length - 1; i >= 0; i--) {
    const {instance, currentTarget, listener} = dispatchListeners[i];
    if (instance !== previousInstance && event.isPropagationStopped()) {
      return;
    }
    // ... (a development-only branch that makes the same call left out)
    executeDispatch(event, listener, currentTarget);
    // ... (the end of that branch left out)
    previousInstance = instance;
  }
} else {
  for (let i = 0; i < dispatchListeners.length; i++) {
    const {instance, currentTarget, listener} = dispatchListeners[i];
    if (instance !== previousInstance && event.isPropagationStopped()) {
      return;
    }

1. Lines 2 and 3: the capture phase runs the list from its end, so the outermost element's handler goes first. Lines 13 and 14: the bubble phase runs it from the start, the target first.
2. Lines 5 to 7 and 16 to 18: before moving to a handler on another element, stop if a handler called stopPropagation.
3. Line 9 calls one handler through executeDispatch:

function executeDispatch(
  event: ReactSyntheticEvent,
  listener: Function,
  currentTarget: EventTarget,
): void {
  event.currentTarget = currentTarget;
  try {
    listener(event);
  } catch (error) {
    reportGlobalError(error);
  }
  event.currentTarget = null;
}

Line 6 sets currentTarget to this handler's element, line 8 calls your handler, and line 12 sets currentTarget back to null. Lines 9 and 10 report an error your handler throws instead of letting it stop the other handlers. (See the file.)

SyntheticEvent: a new object for every dispatch

The e your handler receives is made by SyntheticBaseEvent, in SyntheticEvent.js:

function SyntheticBaseEvent(
  reactName: string | null,
  reactEventType: string,
  targetInst: Fiber | null,
  nativeEvent: {[propName: string]: mixed, ...},
  nativeEventTarget: null | EventTarget,
) {
  this._reactName = reactName;
  this._targetInst = targetInst;
  this.type = reactEventType;
  this.nativeEvent = nativeEvent;
  this.target = nativeEventTarget;
  this.currentTarget = null;
  // ... (copying each field from the native event, and defaultPrevented, left out)
  this.isPropagationStopped = functionThatReturnsFalse;
  return this;
  // ... (the start of the prototype, and preventDefault, left out)
  stopPropagation: function () {
    const event = this.nativeEvent;
    if (!event) {
      return;
    }

    if (event.stopPropagation) {
      event.stopPropagation();
    // ... (a fallback for Internet Explorer left out)
    }

    this.isPropagationStopped = functionThatReturnsTrue;
  },
  // ... (a comment about the old pool left out)
  persist: function () {
    // Modern event system doesn't use pooling.
  },
  // ... (a comment left out)
  isPersistent: functionThatReturnsTrue,

1. Lines 8 to 13 store React's name for the event, the browser's event as nativeEvent, and the target. currentTarget starts as null; executeDispatch fills it in.
2. Lines 18 to 30: stopPropagation calls the browser event's own stopPropagation (line 25), and marks this object as stopped (line 29), which processDispatchQueueItemsInOrder checks.
3. Lines 32 to 34: persist does nothing, and line 36: isPersistent always says yes. Before React 17, event objects were reused, and you had to call persist to keep one. Now each dispatch makes a new one.

Click the button and read what React handed the handler:

1import { note } from "./log.js";2 3export default function App() {4  function handleClick(e) {5    note(`${e.constructor.name}: type ${e.type}, currentTarget ${e.currentTarget.tagName}`);6    note(`nativeEvent is a MouseEvent: ${e.nativeEvent instanceof MouseEvent}. isPersistent(): ${e.isPersistent()}`);7    const key = Object.keys(e.currentTarget).find((name) => name.startsWith("__reactProps$"));8    note(`The button's __reactProps$ holds this onClick: ${e.currentTarget[key].onClick === handleClick}`);9    setTimeout(() => note(`Later: type ${e.type}, target ${e.target.tagName}, currentTarget ${e.currentTarget}`));10  }11 12  return <button onClick={handleClick}>Add to cart</button>;13}

Line 5 prints SyntheticBaseEvent: type click, currentTarget BUTTON. Line 6 prints that nativeEvent is a MouseEvent (in Chrome, a PointerEvent, which is a kind of MouseEvent) and isPersistent() is true. Lines 7 and 8 find the __reactProps$ key on the button and print that its onClick is this very function: that is what getListener read. Line 9 reads the event again after a timer: type click, target BUTTON, and currentTarget null. The object is still yours to read; only currentTarget was cleared by executeDispatch.

React's listeners and yours: who runs first

Because React's handlers run inside its listeners on #root, native listeners elsewhere run before or after them, following the browser's order. This example adds native listeners to document, the button and #root, next to React handlers on a div and the button. Click Add to cart, then pick where to stop the click and click again.

1import { useEffect, useRef, useState } from "react";2import { clearLog, note } from "./log.js";3 4export default function App() {5  const button = useRef(null);6  const [stopIn, setStopIn] = useState("nowhere");7 8  useEffect(() => {9    const root = document.getElementById("root");10    const listen = (target, name, capture) => {11      const listener = (e) => {12        if (name === "document, capture") clearLog();13        note(`${name}: native`);14        if (stopIn === "the button's native listener" && target === button.current) e.stopPropagation();15      };16      target.addEventListener("click", listener, capture);17      return () => target.removeEventListener("click", listener, capture);18    };19    const stops = [20      listen(document, "document, capture", true),21      listen(button.current, "button", false),22      listen(root, "#root, bubble", false),23      listen(document, "document, bubble", false),24    ];25    return () => stops.forEach((stop) => stop());26  }, [stopIn]);27 28  return (29    <>30      <label>31        Stop the click in:{" "}32        <select value={stopIn} onChange={(e) => setStopIn(e.target.value)}>33          <option>nowhere</option>34          <option>the button's onClick</option>35          <option>the button's native listener</option>36        </select>37      </label>38      <div onClickCapture={() => note("div onClickCapture: React")} onClick={() => note("div onClick: React")}>39        <button40          ref={button}41          onClickCapture={() => note("button onClickCapture: React")}42          onClick={(e) => {43            note("button onClick: React");44            if (stopIn === "the button's onClick") e.stopPropagation();45          }}46        >47          Add to cart48        </button>49      </div>50    </>51  );52}

Lines 19 to 24 add the four native listeners; line 12 clears the log when the first of them runs. Lines 38 to 48 are the React handlers. With nothing stopped, the log reads:

1. document, capture: native. The capture phase starts at the top, and document is above the root.
2. div onClickCapture: React, button onClickCapture: React. React's capture listener on #root, outermost first.
3. button: native. The click reaches its target.
4. button onClick: React, div onClick: React. React's bubble listener on #root.
5. #root, bubble: native, then document, bubble: native. The example added its #root listener after createRoot added React's, so it runs second there.

Pick the button's onClick: line 44 calls e.stopPropagation(). The log ends with button onClick: React and #root, bubble: native. React skips the div's onClick, and its call to the browser event's stopPropagation keeps the click from reaching document. The native listener on #root still runs, because stopping only keeps an event from moving on to other elements.

Pick the button's native listener: line 14 stops the click at the button. The log ends with button: native. Neither onClick runs, though the capture handlers already did: the click never reached React's bubble listener. A third-party script that stops clicks this way silences your onClick handlers.

Event priorities choose the update's lane

Back to line 6 of the wrapper: getEventPriority sorts every event name into a priority:

export function getEventPriority(domEventName: DOMEventName): EventPriority {
  switch (domEventName) {
    // Used by SimpleEventPlugin:
    case 'beforetoggle':
    case 'cancel':
    case 'click':
    // ... (more discrete events left out)
    case 'input':
    case 'invalid':
    case 'keydown':
    case 'keypress':
    case 'keyup':
      // ... (more discrete events left out)
      return DiscreteEventPriority;
    case 'drag':
    // ... (drag events left out)
    case 'mousemove':
    // ... (more continuous events left out)
    case 'scroll':
    case 'touchmove':
    case 'wheel':
      // ... (pointer events and enter and leave events left out)
      return ContinuousEventPriority;
    // ... (the message event left out)
    default:
      return DefaultEventPriority;
  }
}

Lines 4 to 14: events that happen once per action, like click, input and keydown, are discrete. Lines 15 to 23: events that fire many times in a row, like mousemove, scroll and wheel, are continuous. Line 26: everything else is default. Each priority is a lane, in ReactEventPriorities.js, lines 25 to 28:

export const DiscreteEventPriority: EventPriority = SyncLane;
export const ContinuousEventPriority: EventPriority = InputContinuousLane;
export const DefaultEventPriority: EventPriority = DefaultLane;
export const IdleEventPriority: EventPriority = IdleLane;

When your handler calls a set function, requestUpdateLane picks the update's lane, a step the What setState really does lesson traced. It (ReactFiberWorkLoop.js, lines 863 to 867) asks resolveUpdatePriority and turns the answer into the update's lane:

export function resolveUpdatePriority(): EventPriority {
  const updatePriority = ReactDOMSharedInternals.p; /* currentUpdatePriority */
  if (updatePriority !== NoEventPriority) {
    return updatePriority;
  }
  const currentEvent = window.event;
  if (currentEvent === undefined) {
    return DefaultEventPriority;
  }
  return getEventPriority(currentEvent.type);
}

1. Lines 2 to 5: the priority dispatchDiscreteEvent set while your handler runs.
2. Lines 6 to 10: if none is set, React looks at window.event, the event the browser is dispatching right now. So even a native addEventListener click handler gives its updates a discrete priority.
3. Line 8: outside any event, like in a timer, the priority is default.

The lane decides when React renders. A SyncLane update is rendered in a microtask right after your handler, before the browser does anything else; other lanes wait for a scheduler task. This example updates the count, then looks at the page in its own microtask. Try every control.

1import { useEffect, useRef, useState } from "react";2import { note } from "./log.js";3 4export default function App() {5  const [count, setCount] = useState(0);6  const counter = useRef(null);7  const nativeButton = useRef(null);8 9  // Updates the count, then looks at the page in a microtask.10  function bump(kind) {11    setCount((n) => n + 1);12    const before = counter.current.textContent;13    queueMicrotask(() => {14      const now = counter.current.textContent;15      note(`${kind}: ${now === before ? "not yet" : "already on screen"}`);16    });17  }18 19  useEffect(() => {20    const button = nativeButton.current;21    const onClick = () => bump("native click listener");22    button.addEventListener("click", onClick);23    return () => button.removeEventListener("click", onClick);24  }, []);25 26  return (27    <>28      <p>Count: <span ref={counter}>{count}</span></p>29      <button onClick={() => bump("onClick")}>Click</button>30      <input onChange={() => bump("onChange")} placeholder="Type" />31      <div onMouseMove={() => bump("onMouseMove")} className="pad">Move the mouse here</div>32      <div onWheel={() => bump("onWheel")} className="pad">Turn the wheel here</div>33      <button onClick={() => setTimeout(() => bump("a timer"))}>Timer</button>34      <button ref={nativeButton}>Native listener</button>35    </>36  );37}

Lines 10 to 17: bump calls setCount, then queues a microtask that compares the count on the page with the one before. Click, typing, and Native listener (lines 19 to 24) log already on screen: discrete events, SyncLane, rendered in React's microtask, which was queued first. Moving the mouse over the box, turning the wheel over the other one, and Timer log not yet: continuous and default lanes wait for a task. This is also why a click interrupts a transition and a timer doesn't, as the concurrent rendering lesson showed. How to read the table: each row is a group of events, the priority and lane their updates get, and when they render.

Portals: a second root that bubbles through the first

A portal puts DOM somewhere else, often straight into body. A click there never passes #root. So react-dom listens on the portal's container too, when the portal mounts, in ReactFiberConfigDOM.js, lines 845 to 847:

export function preparePortalMount(portalInstance: Instance): void {
  listenToAllSupportedEvents(portalInstance);
}

Open the size guide below, then close it.

1import { useState } from "react";2import { createPortal } from "react-dom";3import { listenersOn } from "./spy.js";4import { note } from "./log.js";5 6const modalRoot = document.body.appendChild(document.createElement("div"));7modalRoot.id = "modal-root";8 9function SizeGuide({ onClose }) {10  return createPortal(11    <div className="modal">12      <p>Sizes: S, M, L</p>13      <button onClick={onClose}>Close</button>14    </div>,15    modalRoot,16  );17}18 19export default function App() {20  const [open, setOpen] = useState(false);21 22  function openGuide() {23    setOpen(true);24    setTimeout(() => note(`#modal-root has ${listenersOn(modalRoot).length} listeners`));25  }26 27  function close() {28    note("Close's onClick");29    setOpen(false);30  }31 32  return (33    <section onClick={() => note("the product card's onClick")}>34      <h3>Linen shirt</h3>35      <button onClick={openGuide} disabled={open}>Size guide</button>36      {open && <SizeGuide onClose={close} />}37    </section>38  );39}

Lines 6 and 7 add a #modal-root to the page, and lines 10 to 16 render the guide into it. Size guide logs the product card's onClick, from line 33, then line 24 reports #modal-root has 142 listeners: the same set as #root. Close logs Close's onClick, then the product card's onClick. In the DOM, Close is in body, nowhere near the card. But the click's fiber walk follows return links, and a portal's return is the component that rendered it, inside the card. Open the guide again: the count stays at 142, because the marker from listenToAllSupportedEvents stops a second set.

One more check keeps a click from running handlers twice when a portal's container sits inside another root's container. Before the walk, dispatchEventForPluginEventSystem climbs from the target to the nearest root or portal, in DOMPluginEventSystem.js:

const nodeTag = node.tag;
if (nodeTag === HostRoot || nodeTag === HostPortal) {
  let container = node.stateNode.containerInfo;
  if (isMatchingRootContainer(container, targetContainerNode)) {
    break;
  }
  if (nodeTag === HostPortal) {
    // ... (comments left out)
    let grandNode = node.return;
    while (grandNode !== null) {
      const grandTag = grandNode.tag;
      if (grandTag === HostRoot || grandTag === HostPortal) {
        const grandContainer = grandNode.stateNode.containerInfo;
        if (
          isMatchingRootContainer(grandContainer, targetContainerNode)
        ) {
          // This is the rootContainer we're looking for and we found it as
          // a parent of the Portal. That means we can ignore it because the
          // Portal will bubble through to us.
          return;
        }

1. Line 2: a root or a portal.
2. Lines 4 to 6: its container is the one whose listener is running, as for our guide and #modal-root. Good: go on from the target.
3. Lines 7 to 20: a portal whose container is not this listener's. If this listener's container is further up, the outer listener returns at line 20 and leaves the click to the portal container's listener, which bubbles through the React tree anyway.

A menu that closes the moment it opens

Here is a bug that comes straight from this machinery. A sort menu opens on click and closes when you click outside it, with a native listener on document added while it's open. Click Sort by.

1import { useEffect, useRef, useState } from "react";2import { note } from "./log.js";3 4export default function App() {5  const [open, setOpen] = useState(false);6  const menu = useRef(null);7 8  useEffect(() => {9    if (!open) return;10    note("effect: listen for clicks on document");11    function closeOnOutsideClick(e) {12      if (menu.current.contains(e.target)) return;13      note("document heard a click outside: close");14      setOpen(false);15    }16    document.addEventListener("click", closeOnOutsideClick);17    return () => document.removeEventListener("click", closeOnOutsideClick);18  }, [open]);19 20  function openMenu() {21    note("onClick: open the menu");22    setOpen(true);23  }24 25  return (26    <>27      <button onClick={openMenu}>Sort by</button>28      {open && (29        <ul ref={menu} className="menu">30          <li>Price</li>31          <li>Rating</li>32        </ul>33      )}34    </>35  );36}

In a browser, the menu never shows, and the log reads onClick: open the menu, effect: listen for clicks on document, document heard a click outside: close. The click that opened the menu also closed it. Follow it:

1. The click reaches React's bubble listener on #root, and openMenu (lines 20 to 23) calls setOpen(true). A click is discrete, so the update gets SyncLane.
2. When a listener returns, the browser runs the microtasks waiting. React's microtask renders and commits the open menu at once, before the click moves on to document.
3. Effects usually run after the browser paints. Not after a SyncLane commit: the end of the commit runs them straight away.

// If the passive effects are the result of a discrete render, flush them
// synchronously at the end of the current task so that the result is
// immediately observable. Otherwise, we assume that they are not
// order-dependent and do not need to be observed by external systems, so we
// can wait until after paint.
// TODO: We can optimize this by not scheduling the callback earlier. Since we
// currently schedule the callback in multiple places, will wait until those
// are consolidated.
if (
  includesSyncLane(pendingEffectsLanes) &&
  (disableLegacyMode || root.tag !== LegacyRoot)
) {
  flushPendingEffects();
}

Lines 9 to 13: the pending effects include SyncLane, so flushPendingEffects runs them now. The effect on lines 8 to 18 adds its document listener, and the same click, still on its way up, reaches document and runs it. Line 12 checks whether the click was inside the menu, but the click was on the Sort by button, outside the <ul>. So it closes.

A click your code sends with dispatchEvent or click() doesn't show the bug: microtasks wait until that call returns, so the effect runs after the click has passed document. A test that clicks this way passes while real users see a broken menu. The fix is to treat the button as part of the menu, as the menu's users do:

1import { useEffect, useRef, useState } from "react";2import { note } from "./log.js";3 4export default function App() {5  const [open, setOpen] = useState(false);6  const dropdown = useRef(null);7 8  useEffect(() => {9    if (!open) return;10    note("effect: listen for clicks on document");11    function closeOnOutsideClick(e) {12      if (dropdown.current.contains(e.target)) return;13      note("document heard a click outside: close");14      setOpen(false);15    }16    document.addEventListener("click", closeOnOutsideClick);17    return () => document.removeEventListener("click", closeOnOutsideClick);18  }, [open]);19 20  function openMenu() {21    note("onClick: open the menu");22    setOpen(true);23  }24 25  return (26    <div ref={dropdown}>27      <button onClick={openMenu}>Sort by</button>28      {open && (29        <ul className="menu">30          <li>Price</li>31          <li>Rating</li>32        </ul>33      )}34    </div>35  );36}

Line 26 puts the ref on a div around both the button and the menu, and line 12 ignores clicks inside it. The opening click is now inside, so the menu stays open; a click anywhere else closes it. Listening for pointerdown instead of click also works, because the press that starts the opening click happens before the listener exists.

Common mix-ups

• "React adds a listener to every element with onClick." No. It adds a capture and a bubble listener per kind of event, once, to the root container.
• "e is the browser's event." No. It's a SyntheticBaseEvent; the browser's is e.nativeEvent.
• "You must call e.persist() to read e later." No. Since React 17 there's no pooling. Only currentTarget is cleared after your handler.
• "onChange is the browser's change event." No. On a text box, ChangeEventPlugin fires it on input, every key.
• "A native stopPropagation can't affect React handlers." No. Stopped below the root, a click never reaches React's bubble listener, so no onClick runs.
• "onClickCapture runs before every native listener." No. Capture listeners above the root, like on document, run first.
• "Portal clicks bubble to React parents through the DOM." No. The portal's container has its own listeners, and the fiber walk climbs through the portal to its React parent.

Practice exercises

import { useEffect, useRef } from "react";
import { note } from "./log.js";

export default function App() {
  const button = useRef(null);

  useEffect(() => {
    const node = button.current;
    const onNativeClick = () => note("native listener");
    node.addEventListener("click", onNativeClick);
    return () => node.removeEventListener("click", onNativeClick);
  }, []);

  return (
    <button ref={button} onClick={() => note("onClick")}>
      Add to cart
    </button>
  );
}

import { useEffect, useRef } from "react";
import { note } from "./log.js";

export default function App() {
  const button = useRef(null);

  useEffect(() => {
    const node = button.current;
    const onNativeClick = () => note("native listener");
    node.addEventListener("click", onNativeClick);
    return () => node.removeEventListener("click", onNativeClick);
  }, []);

  return (
    <button ref={button} onClick={() => note("onClick")}>
      Add to cart
    </button>
  );
}

import { note } from "./log.js";

export default function App() {
  function handleClick(e) {
    note(`now: ${e.currentTarget.tagName}`);
    setTimeout(() => note(`later: ${e.currentTarget}`));
  }

  return <button onClick={handleClick}>Add to cart</button>;
}

import { note } from "./log.js";

export default function App() {
  function handleClick(e) {
    note(`now: ${e.currentTarget.tagName}`);
    setTimeout(() => note(`later: ${e.currentTarget}`));
  }

  return <button onClick={handleClick}>Add to cart</button>;
}

1import { note } from "./log.js";2 3// TODO: wrap `listener` so that, for a click listener on #root, it first4// notes "#root capture listener runs" or "#root bubble listener runs".5const addEventListener = EventTarget.prototype.addEventListener;6EventTarget.prototype.addEventListener = function (type, listener, options) {7  return addEventListener.call(this, type, listener, options);8};9 10export default function App() {11  return <button onClick={() => note("onClick runs")}>Add to cart</button>;12}

1import { note } from "./log.js";2 3const addEventListener = EventTarget.prototype.addEventListener;4EventTarget.prototype.addEventListener = function (type, listener, options) {5  const capture = options === true || options?.capture === true;6  if (type === "click" && this.id === "root") {7    const original = listener;8    listener = (event) => {9      note(`#root ${capture ? "capture" : "bubble"} listener runs`);10      return original(event);11    };12  }13  return addEventListener.call(this, type, listener, options);14};15 16export default function App() {17  return <button onClick={() => note("onClick runs")}>Add to cart</button>;18}

const log = [];
const root = { tag: "HostRoot", props: {}, return: null };
// A component's props are never event listeners, even one named onClick.
const app = { tag: "FunctionComponent", props: { onClick: () => log.push("App onClick") }, return: root };
const card = {
  tag: "HostComponent",
  props: { onClick: () => log.push("card onClick"), onClickCapture: () => log.push("card onClickCapture") },
  return: app,
};
const button = {
  tag: "HostComponent",
  props: { onClick: () => log.push("button onClick"), onClickCapture: () => log.push("button onClickCapture") },
  return: card,
};

// Runs the listeners like processDispatchQueue: from the end in the capture phase.
function dispatch(listeners, inCapturePhase) {
  const order = inCapturePhase ? [...listeners].reverse() : listeners;
  for (const listener of order) listener();
}

// TODO: walk from `fiber` up through `return`, and collect props[name]
// from host fibers only, like accumulateSinglePhaseListeners.
function accumulate(fiber, name) {
  const listeners = [];
  return listeners;
}

dispatch(accumulate(button, "onClickCapture"), true);
dispatch(accumulate(button, "onClick"), false);
console.log(log.join(", "));

const log = [];
const root = { tag: "HostRoot", props: {}, return: null };
// A component's props are never event listeners, even one named onClick.
const app = { tag: "FunctionComponent", props: { onClick: () => log.push("App onClick") }, return: root };
const card = {
  tag: "HostComponent",
  props: { onClick: () => log.push("card onClick"), onClickCapture: () => log.push("card onClickCapture") },
  return: app,
};
const button = {
  tag: "HostComponent",
  props: { onClick: () => log.push("button onClick"), onClickCapture: () => log.push("button onClickCapture") },
  return: card,
};

// Runs the listeners like processDispatchQueue: from the end in the capture phase.
function dispatch(listeners, inCapturePhase) {
  const order = inCapturePhase ? [...listeners].reverse() : listeners;
  for (const listener of order) listener();
}

function accumulate(fiber, name) {
  const listeners = [];
  for (let instance = fiber; instance !== null; instance = instance.return) {
    if (instance.tag === "HostComponent" && instance.props[name]) listeners.push(instance.props[name]);
  }
  return listeners;
}

dispatch(accumulate(button, "onClickCapture"), true);
dispatch(accumulate(button, "onClick"), false);
console.log(log.join(", "));

1import { useEffect, useRef, useState } from "react";2import { note } from "./log.js";3 4export default function App() {5  const [open, setOpen] = useState(false);6  const menu = useRef(null);7 8  useEffect(() => {9    if (!open) return;10    note("effect: listen for clicks on document");11    function closeOnOutsideClick(e) {12      if (menu.current.contains(e.target)) return;13      note("document heard a click outside: close");14      setOpen(false);15    }16    document.addEventListener("click", closeOnOutsideClick);17    return () => document.removeEventListener("click", closeOnOutsideClick);18  }, [open]);19 20  function openMenu() {21    note("onClick: open the menu");22    setOpen(true);23  }24 25  return (26    <>27      <button onClick={openMenu}>Sort by</button>28      {open && (29        <ul ref={menu} className="menu">30          <li>Price</li>31          <li>Rating</li>32        </ul>33      )}34    </>35  );36}

1import { useEffect, useRef, useState } from "react";2import { note } from "./log.js";3 4export default function App() {5  const [open, setOpen] = useState(false);6  const dropdown = useRef(null);7 8  useEffect(() => {9    if (!open) return;10    note("effect: listen for clicks on document");11    function closeOnOutsideClick(e) {12      if (dropdown.current.contains(e.target)) return;13      note("document heard a click outside: close");14      setOpen(false);15    }16    document.addEventListener("click", closeOnOutsideClick);17    return () => document.removeEventListener("click", closeOnOutsideClick);18  }, [open]);19 20  function openMenu() {21    note("onClick: open the menu");22    setOpen(true);23  }24 25  return (26    <div ref={dropdown}>27      <button onClick={openMenu}>Sort by</button>28      {open && (29        <ul className="menu">30          <li>Price</li>31          <li>Rating</li>32        </ul>33      )}34    </div>35  );36}

1import { useEffect, useRef, useState } from "react";2 3export default function App() {4  const [count, setCount] = useState(0);5  const box = useRef(null);6 7  // A widget library stops every click inside its box.8  useEffect(() => {9    const node = box.current;10    const stop = (e) => e.stopPropagation();11    node.addEventListener("click", stop);12    return () => node.removeEventListener("click", stop);13  }, []);14 15  return (16    <div ref={box}>17      <button onClick={() => setCount(count + 1)}>Add to cart ({count})</button>18    </div>19  );20}

1import { useEffect, useRef, useState } from "react";2 3export default function App() {4  const [count, setCount] = useState(0);5  const box = useRef(null);6 7  // A widget library stops every click inside its box.8  useEffect(() => {9    const node = box.current;10    const stop = (e) => e.stopPropagation();11    node.addEventListener("click", stop);12    return () => node.removeEventListener("click", stop);13  }, []);14 15  return (16    <div ref={box}>17      <button onClickCapture={() => setCount(count + 1)}>Add to cart ({count})</button>18    </div>19  );20}

Check your understanding

Key takeaways

• createRoot calls listenToAllSupportedEvents: a capture listener and, for events that bubble, a bubble listener per kind of event, on the root container. Portals get the same on their container.
• Each listener runs dispatchEvent, which finds the target's fiber, lets the plugins build React events, and runs your handlers inside batchedUpdates.
• Plugins map browser events to props: SimpleEventPlugin for most, ChangeEventPlugin for onChange, EnterLeaveEventPlugin for enter and leave.
• accumulateSinglePhaseListeners climbs return links from the target and reads host fibers' props from the DOM node; capture runs the list from the end, bubble from the start.
• e is a new SyntheticBaseEvent per dispatch, with nativeEvent inside; no pooling since React 17.
• getEventPriority makes clicks and keys discrete (SyncLane), mouse moves and scrolls continuous, and the rest default.

Coming next: Hydration inside. It shows how React claims HTML that is already on the page, including the events that arrive before it has.