Skip to content
Tutorials Center
My learning

Topics

React Reference ยท Props and Attributes

React capture phase handlers

Learn React capture phase handlers such as onClickCapture: the order of capture and bubble phases, when to use capture, and how to stop events early.

An event travels in two directions. First it goes down from the root to the element that was clicked (the capture phase), then back up (the bubble phase). Ordinary handlers such as onClick run on the way up. To run a handler on the way down, add Capture to its name: onClickCapture, onKeyDownCapture, onFocusCapture, and so on.

Capture handlers run before any bubble handler for the same event, and they can stop the event before the target ever sees it. Most code never needs them; they are useful for logging, analytics, and for blocking interaction inside a subtree.

JSX
<div onClickCapture={() => console.log('first, going down')}>
  <button onClick={() => console.log('then the target, going up')}>Go</button>
</div>

Try it

The order of capture and bubble handlers

A capture handler can stop the event so nothing deeper reacts. This disables a whole group of controls without touching each one.

Blocking clicks in a subtree

Syntax

JSX
<element onEventCapture={handler} />
Name Description
onClickCapture, onChangeCapture, onKeyDownCapture, onPointerDownCapture, onFocusCapture, ... The name of any event handler prop with Capture appended. The handler receives a SyntheticEvent.

Usage notes

  • Order: root capture, then deeper captures, the target's own handlers, then bubble handlers from the target up to the root.
  • stopPropagation() in a capture handler prevents the event from reaching deeper capture handlers, the target and all bubble handlers.
  • preventDefault() works the same in either phase.
  • Not every event bubbles natively, but in React onFocus and onBlur bubble (React uses focusin and focusout), so onFocusCapture is rarely needed there.
  • Alternative for disabling: the inert attribute or disabled on a fieldset is usually clearer than blocking events; see inert.
  • Not a replacement for state. If you find yourself stopping events to implement business rules, move the rule into the handler or into the state update.
  • Custom components only get capture props if you forward them yourself.