32

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?

Mayron
  • 2,146
  • 4
  • 25
  • 51
  • Does this answer your question? [onKeyPress Vs. onKeyUp and onKeyDown](https://stackoverflow.com/questions/3396754/onkeypress-vs-onkeyup-and-onkeydown) – Adam Strauss Jan 22 '20 at 05:56
  • 3
    @AdamStrauss no sorry. I know about those but react adds new ones ending in "Capture" and I don't know what they do or how they differ. – Mayron Jan 22 '20 at 06:05

1 Answers1

66

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.

Here is an example of DOM event flow clicking on <td>

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

Matin Kajabadi
  • 3,414
  • 1
  • 17
  • 21
  • 4
    That's the best explanation I have seen of the three phases. Thank you for that. So when does onKeyUpCapture get triggered? I assume it is before onKeyUp because, from my understanding, onKeyUp gets called during the target phase? Does onKeyUpCapture occur once the target is captured? Is there much benefit in using this if it gets called instantly before onKeyUp if this is how it works? – Mayron Jan 22 '20 at 07:17
  • 5
    Correct, as I explained `onKeyUpCapture` will be triggered first coming from the window through the element's ancestors. ( depends where do you want to have that). After it reaches the target it will trigger the target and finally it will bubble up from target toward it's parent. You barely would need `Capture` in your code unless there is a reason you want to handle something before it reaches the actual target element like having a complex animation. – Matin Kajabadi Jan 22 '20 at 07:34
  • 1
    Thanks @MatinKajabadifor for describing an example of why someone might be interested in `onKeyUpCapture` at all. – BradGreens Jan 22 '21 at 19:00