🧬 Synthetic Events

What Is a Synthetic Event?

A SyntheticEvent is React's cross-browser wrapper around the native DOM event. Picture a universal power adapter: whatever the wall socket looks like in a given country, your laptop always plugs into the same connector. React does that for events — the browser underneath may expose slightly different APIs, but your handler always receives the same, predictable object.

Because the interface is consistent, the browser-sniffing code developers wrote a decade ago simply disappears. You write e.key === 'Enter' once and trust it works everywhere.

Why React Wraps Events

Before frameworks normalized this, attaching a listener meant guarding against browsers that disagreed on the API. It looked like this:

// The bad old days — cross-browser branching by hand
function addListener(el, type, handler) {
  if (el.addEventListener) {
    el.addEventListener(type, handler, false);   // modern browsers
  } else if (el.attachEvent) {
    el.attachEvent('on' + type, handler);        // old Internet Explorer
  } else {
    el['on' + type] = handler;                   // ancient fallback
  }
}

React makes that entire category of code obsolete. You declare the handler in JSX and the wrapper guarantees a single, uniform shape:

function Button() {
  const handleClick = (e) => {
    // e is a SyntheticEvent — identical shape in every browser
    console.log(e.type); // "click"
  };

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

Delegation from the Root

Here's a surprise: when you write onClick on a hundred buttons, React does not attach a hundred listeners. It attaches one listener to your app's root container and lets events bubble up to it. When an event arrives, React figures out which component it belongs to and calls the right handler with a freshly built SyntheticEvent.

Properties & Event Families

Every SyntheticEvent shares a common set of properties, and specialized events add more. Here's the common core:

Mouse events

function MouseDemo() {
  const handleMouse = (e) => {
    console.log(e.type, e.button, e.clientX, e.clientY);
    console.log('modifiers', e.altKey, e.ctrlKey, e.shiftKey);
  };

  return (
    <div
      onClick={handleMouse}
      onMouseEnter={handleMouse}
      onMouseLeave={handleMouse}
      onContextMenu={handleMouse}
    >
      Interact with me
    </div>
  );
}

Keyboard events

function KeyboardDemo() {
  const handleKey = (e) => {
    console.log('key:', e.key);     // "a", "Enter", "ArrowUp"…
    console.log('code:', e.code);   // physical key, e.g. "KeyA"
    console.log('repeat:', e.repeat);
  };

  return <input onKeyDown={handleKey} placeholder="Type here" />;
}

Focus & form events

function FieldDemo() {
  const handleFocus = (e) => console.log('focused', e.target.name);
  const handleBlur  = (e) => console.log('blurred, related:', e.relatedTarget);
  const handleChange = (e) => console.log('value:', e.target.value);

  return (
    <input
      name="email"
      onFocus={handleFocus}
      onBlur={handleBlur}
      onChange={handleChange}
    />
  );
}

Event Pooling (and Its Removal)

Historically, React reused a small pool of event objects for performance. After your handler finished, React would reset the event's properties to null and recycle the object for the next event. That optimization bit anyone who tried to use the event asynchronously.

// React 16 and earlier — event pooling in effect
function Legacy() {
  const handleClick = (e) => {
    console.log(e.type); // "click" — fine, synchronous

    setTimeout(() => {
      console.log(e.type); // null! the event was recycled
    }, 1000);

    // The old workaround: opt out of pooling for this event
    e.persist();
    setTimeout(() => console.log(e.type), 1000); // now "click"
  };

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

function Modern() {
  const handleClick = (e) => {
    console.log(e.type);               // "click"
    setTimeout(() => console.log(e.type), 1000); // still "click"
  };

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

Reaching the Native Event

Occasionally you need a property React doesn't surface, or you're integrating with a library expecting a raw DOM event. Every SyntheticEvent carries the original on e.nativeEvent:

function NativeAccess() {
  const handleClick = (e) => {
    const native = e.nativeEvent;    // the real browser MouseEvent
    console.log('synthetic type:', e.type);
    console.log('native type:', native.type);
    // Some low-level properties live only on the native event:
    console.log('composed path:', native.composedPath());
  };

  return <div onClick={handleClick}>Compare synthetic vs native</div>;
}

For events React doesn't expose as a prop at all (custom events, certain non-passive listeners), attach a native listener directly with a ref and clean it up in an effect:

import { useRef, useEffect } from 'react';

function CustomListener() {
  const boxRef = useRef(null);

  useEffect(() => {
    const el = boxRef.current;
    if (!el) return;

    const handler = (e) => console.log('native custom event', e.detail);
    el.addEventListener('my-custom-event', handler);

    // Always clean up — this prevents duplicate listeners and leaks.
    return () => el.removeEventListener('my-custom-event', handler);
  }, []);

  return <div ref={boxRef}>Listening for a native custom event</div>;
}

Common Gotchas

1. Async access to mutable DOM properties

The event survives async work in React 17+, but the element it points to can change. Snapshot what you need first:

const handleChange = async (e) => {
  // ✅ Capture the value NOW, before any await
  const value = e.target.value;

  await saveToServer(value);

  // ❌ Reading e.target.value here could be a newer keystroke
  console.log('saved:', value);
};

2. target vs currentTarget in delegated handlers

function List() {
  const handleClick = (e) => {
    // currentTarget is always the <ul> (where the handler lives)
    // target is whatever <li> or child was actually clicked
    console.log(e.currentTarget.tagName, '←', e.target.tagName);
  };

  return (
    <ul onClick={handleClick}>
      <li>One</li>
      <li>Two</li>
    </ul>
  );
}

3. Native listeners fire outside React's timeline

An event caught by a manual addEventListener isn't part of React's batched update cycle in the same way. Keep such listeners for genuinely native needs (scroll performance, third-party widgets) and clean them up in the effect's return function.

Practice & Quiz

function EventLogger() {
  const [log, setLog] = useState([]);

  const record = (e) => {
    // TODO: append { type, tag } and keep only the last 5
  };

  return (
    <div onClick={record} onKeyDown={record}>
      <input placeholder="Type or click" />
      <ul>{log.map((x, i) => <li key={i}>{x.type} — {x.tag}</li>)}</ul>
    </div>
  );
}

const record = (e) => {
  const entry = { type: e.type, tag: e.target.tagName };
  setLog((prev) => [...prev.slice(-4), entry]);
};

const handleClick = (e) => {
  console.log('synthetic:', e.type);        // "click"
  console.log('native:', e.nativeEvent.type); // "click"
  console.log('path:', e.nativeEvent.composedPath()); // native-only
};

Best Practices & Pitfalls

✅ Do

• Trust the abstraction — write standard event code and let React normalize browsers
• Snapshot mutable values (like e.target.value) before any await
• Reach for e.nativeEvent only when React genuinely doesn't expose what you need
• Clean up any manual addEventListener in the effect's cleanup function

❌ Don't

• Rely on old event-pooling behavior or add e.persist() "just in case" — it's obsolete
• Assume e.target is the element you attached the handler to — that's currentTarget
• Mix a native document-level listener with React handlers without understanding the ordering
• Store the whole event object in state to "use later" — copy the fields you need instead

Summary

📚 Additional Resources

• React docs — Common components: the React event object
• React 17 — Changes to event delegation
• MDN — The Event interface

🚀 What's Next?

You understand the event object inside and out. Now let's put it to constant use where events matter most: Forms in React — controlled inputs, the value/onChange loop, validation, and managing many fields with one handler.