In React, what is the difference between onKeyUp and onKeyUpCapture (and onKeyDown/Capture)?

Question

I searched for documentation and questions for this but was surprised to not be able to find one.

In the React index.d.ts file it shows:

// Keyboard Events
onKeyDown?: KeyboardEventHandler<T>;
onKeyDownCapture?: KeyboardEventHandler<T>;
onKeyPress?: KeyboardEventHandler<T>;
onKeyPressCapture?: KeyboardEventHandler<T>;
onKeyUp?: KeyboardEventHandler<T>;
onKeyUpCapture?: KeyboardEventHandler<T>;

And I wanted to use onKeyUp but then I noticed the two versions. What is the difference between this and onKeyUpCapture, and what are the benefits of one over the other? When would I use each?

Answer 1

Event handlers in react passes an instances of SyntheticEvent, a cross-browser wrapper around the browser’s native event. The term capture is not related to React. In fact it's a concept from DOM HTML Event.

The are 3 general phases of event propagation DOM Events:

The capture phase: The event object propagates through the target’s ancestors from the Window to the target’s parent. (the event goes down to the element). You barely might want to use it in real code.

The target phase: The event object arrives at the event object’s event target. This phase is also known as the at-target phase. If the event type indicates that the event doesn’t bubble, then the event object will halt after completion of this phase.

The bubble phase: The event object propagates through the target’s ancestors in reverse order, starting with the target’s parent and ending with the Window. This phase is also known as the bubbling phase.

Event objects are dispatched to an event target. But before dispatch can begin, the event object’s propagation path must first be determined.

The propagation path is an ordered list of current event targets through which the event passes. This propagation path reflects the hierarchical tree structure of the document. The last item in the list is the event target, and the preceding items in the list are referred to as the target’s ancestors, with the immediately preceding item as the target’s parent.

As you can see in this picture, it shows the capture phase that starts from the window going through the ancestors chain down to the element target. Then when it gets to the target element, it triggers there - target phase And finally it bubbles up to target’s ancestors - bubbling phase (will stop bubbling if any ancestors stopPropagation

So React is giving you the capture phase by appending it to onKeyUp which is onKeyUpCapture

Example of 3 different propagation phases