Event Handling and Synthetic Events

React Events Are Not DOM Events

When you write onClick={handler} in React, you are not adding an onclick attribute or calling addEventListener on that DOM element. React uses event delegation — it attaches a single listener to the root of your application and dispatches events to the correct component handler.

function Button() {
  function handleClick(event) {
    // event is a SyntheticEvent, not a native MouseEvent
    console.log(event.constructor.name); // SyntheticBaseEvent
    console.log(event.nativeEvent.constructor.name); // MouseEvent
  }

  return <button onClick={handleClick}>Click me</button>;
}

Event Delegation: How It Works

Before React 17, all events were attached to document. Since React 17, events are attached to the root DOM container (#root):

// React 17+: listener attached to root container, not document
const root = document.getElementById('root');
// Internally, React does something like:
// root.addEventListener('click', dispatchEvent, true);

This change matters for micro-frontends and embedding React inside non-React pages — events no longer leak to document.

SyntheticEvent: The Wrapper

React wraps native browser events in a SyntheticEvent that normalizes behavior across browsers:

function Input() {
  function handleChange(event) {
    // SyntheticEvent properties mirror native events:
    event.target;          // The DOM element
    event.currentTarget;   // The element with the handler
    event.type;            // 'change'
    event.preventDefault();
    event.stopPropagation();

    // Access the real native event:
    event.nativeEvent;     // The original DOM event
  }

  return <input onChange={handleChange} />;
}

The onChange Difference

React's onChange fires on every keystroke, unlike the native change event which fires on blur:

// React onChange = fires on every character typed
<input onChange={(e) => setQuery(e.target.value)} />

// Native change event = fires when input loses focus
// element.addEventListener('change', handler);

This is one of the most significant deviations from native DOM behavior. React chose this because firing on every keystroke is what developers almost always want for controlled inputs.

Event Pooling: Removed in React 17

Before React 17, SyntheticEvent objects were pooled — after the event handler finished, all properties were nullified and the object was returned to a pool for reuse:

// React 16 (broken):
function handleClick(event) {
  setTimeout(() => {
    console.log(event.type); // null! Event was pooled.
  }, 100);
}

// React 16 workaround:
function handleClick(event) {
  event.persist(); // Remove from pool
  setTimeout(() => {
    console.log(event.type); // 'click' — works now
  }, 100);
}

// React 17+: Pooling removed entirely.
// Events work as expected in async code.

stopPropagation Gotchas

stopPropagation in React only stops propagation within React's event system, not necessarily in the native DOM:

function App() {
  // This native listener on document will fire BEFORE
  // React's delegated handler, because React 17+ uses
  // the root container, not document.
  useEffect(() => {
    document.addEventListener('click', () => {
      console.log('document click'); // Fires first!
    });
  }, []);

  function handleClick(event) {
    event.stopPropagation(); // Stops React propagation
    console.log('button click');
    // But document listener already fired
  }

  return <button onClick={handleClick}>Click</button>;
}

Production Scenario: Form Submission with Keyboard

function SearchForm({ onSearch }) {
  const [query, setQuery] = useState('');

  function handleSubmit(event) {
    event.preventDefault(); // Prevent page reload
    if (query.trim()) {
      onSearch(query.trim());
    }
  }

  function handleKeyDown(event) {
    // event.key is normalized by SyntheticEvent
    if (event.key === 'Escape') {
      setQuery('');
      event.target.blur();
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        onKeyDown={handleKeyDown}
        placeholder="Search..."
      />
      <button type="submit">Search</button>
    </form>
  );
}

Challenge: Fix the Event Bug

Event Propagation Debugging