This reference guide documents theSyntheticEvent wrapper that forms part of React’s Event System. See theHandling Events guide to learn more.

Overview

Your event handlers will be passed instances ofSyntheticEvent, a cross-browser wrapper around the browser’s native event. It has the same interface as the browser’s native event, includingstopPropagation() andpreventDefault(), except the events work identically across all browsers.

If you find that you need the underlying browser event for some reason, simply use thenativeEvent attribute to get it. The synthetic events are different from, and do not map directly to, the browser’s native events. For example inonMouseLeaveevent.nativeEvent will point to amouseout event. The specific mapping is not part of the public API and may change at any time. EverySyntheticEvent object has the following attributes:

boolean bubblesboolean cancelableDOMEventTarget currentTargetboolean defaultPreventednumber eventPhaseboolean isTrustedDOMEvent nativeEventvoidpreventDefault()booleanisDefaultPrevented()voidstopPropagation()booleanisPropagationStopped()voidpersist()DOMEventTarget targetnumber timeStampstring type

Note:

As of v17,e.persist() doesn’t do anything because theSyntheticEvent is no longerpooled.

Note:

As of v0.14, returningfalse from an event handler will no longer stop event propagation. Instead,e.stopPropagation() ore.preventDefault() should be triggered manually, as appropriate.

Supported Events

React normalizes events so that they have consistent properties across different browsers.

The event handlers below are triggered by an event in the bubbling phase. To register an event handler for the capture phase, appendCapture to the event name; for example, instead of usingonClick, you would useonClickCapture to handle the click event in the capture phase.

• Clipboard Events
• Composition Events
• Keyboard Events
• Focus Events
• Form Events
• Generic Events
• Mouse Events
• Pointer Events
• Selection Events
• Touch Events
• UI Events
• Wheel Events
• Media Events
• Image Events
• Animation Events
• Transition Events
• Other Events

Reference

Clipboard Events

Event names:

onCopy onCut onPaste

Properties:

DOMDataTransfer clipboardData

Composition Events

Event names:

onCompositionEnd onCompositionStart onCompositionUpdate

Properties:

string data

Keyboard Events

Event names:

onKeyDown onKeyPress onKeyUp

Properties:

boolean altKeynumber charCodeboolean ctrlKeybooleangetModifierState(key)string keynumber keyCodestring localenumber locationboolean metaKeyboolean repeatboolean shiftKeynumber which

Thekey property can take any of the values documented in theDOM Level 3 Events spec.

Focus Events

Event names:

onFocus onBlur

These focus events work on all elements in the React DOM, not just form elements.

Properties:

DOMEventTarget relatedTarget

onFocus

TheonFocus event is called when the element (or some element inside of it) receives focus. For example, it’s called when the user clicks on a text input.

functionExample(){return(<inputonFocus={(e)=>{        console.log('Focused on input');}}placeholder="onFocus is triggered when you click this input."/>)}

onBlur

TheonBlur event handler is called when focus has left the element (or left some element inside of it). For example, it’s called when the user clicks outside of a focused text input.

functionExample(){return(<inputonBlur={(e)=>{        console.log('Triggered because this input lost focus');}}placeholder="onBlur is triggered when you click this input and then you click outside of it."/>)}

Detecting Focus Entering and Leaving

You can use thecurrentTarget andrelatedTarget to differentiate if the focusing or blurring events originated fromoutside of the parent element. Here is a demo you can copy and paste that shows how to detect focusing a child, focusing the element itself, and focus entering or leaving the whole subtree.

functionExample(){return(<divtabIndex={1}onFocus={(e)=>{if(e.currentTarget=== e.target){          console.log('focused self');}else{          console.log('focused child', e.target);}if(!e.currentTarget.contains(e.relatedTarget)){// Not triggered when swapping focus between children          console.log('focus entered self');}}}onBlur={(e)=>{if(e.currentTarget=== e.target){          console.log('unfocused self');}else{          console.log('unfocused child', e.target);}if(!e.currentTarget.contains(e.relatedTarget)){// Not triggered when swapping focus between children          console.log('focus left self');}}}><inputid="1"/><inputid="2"/></div>);}

Form Events

Event names:

onChange onInput onInvalid onReset onSubmit

For more information about the onChange event, seeForms.

Generic Events

Event names:

onError onLoad

Mouse Events

Event names:

onClick onContextMenu onDoubleClick onDrag onDragEnd onDragEnter onDragExitonDragLeave onDragOver onDragStart onDrop onMouseDown onMouseEnter onMouseLeaveonMouseMove onMouseOut onMouseOver onMouseUp

TheonMouseEnter andonMouseLeave events propagate from the element being left to the one being entered instead of ordinary bubbling and do not have a capture phase.

Properties:

boolean altKeynumber buttonnumber buttonsnumber clientXnumber clientYboolean ctrlKeybooleangetModifierState(key)boolean metaKeynumber pageXnumber pageYDOMEventTarget relatedTargetnumber screenXnumber screenYboolean shiftKey

Pointer Events

Event names:

onPointerDown onPointerMove onPointerUp onPointerCancel onGotPointerCaptureonLostPointerCapture onPointerEnter onPointerLeave onPointerOver onPointerOut

TheonPointerEnter andonPointerLeave events propagate from the element being left to the one being entered instead of ordinary bubbling and do not have a capture phase.

Properties:

As defined in theW3 spec, pointer events extendMouse Events with the following properties:

number pointerIdnumber widthnumber heightnumber pressurenumber tangentialPressurenumber tiltXnumber tiltYnumber twiststring pointerTypeboolean isPrimary

A note on cross-browser support:

Pointer events are not yet supported in every browser (at the time of writing this article, supported browsers include: Chrome, Firefox, Edge, and Internet Explorer). React deliberately does not polyfill support for other browsers because a standard-conform polyfill would significantly increase the bundle size ofreact-dom.

If your application requires pointer events, we recommend adding a third party pointer event polyfill.

Selection Events

Event names:

onSelect

Touch Events

Event names:

onTouchCancel onTouchEnd onTouchMove onTouchStart

Properties:

boolean altKeyDOMTouchList changedTouchesboolean ctrlKeybooleangetModifierState(key)boolean metaKeyboolean shiftKeyDOMTouchList targetTouchesDOMTouchList touches

UI Events

Event names:

onScroll

Note

Starting with React 17, theonScroll eventdoes not bubble in React. This matches the browser behavior and prevents the confusion when a nested scrollable element fires events on a distant parent.

Properties:

number detailDOMAbstractView view

Wheel Events

Event names:

onWheel

Properties:

number deltaModenumber deltaXnumber deltaYnumber deltaZ

Media Events

Event names:

onAbort onCanPlay onCanPlayThrough onDurationChange onEmptied onEncryptedonEnded onError onLoadedData onLoadedMetadata onLoadStart onPause onPlayonPlaying onProgress onRateChange onSeeked onSeeking onStalled onSuspendonTimeUpdate onVolumeChange onWaiting

Image Events

Event names:

onLoad onError

Animation Events

Event names:

onAnimationStart onAnimationEnd onAnimationIteration

Properties:

string animationNamestring pseudoElementfloat elapsedTime

Transition Events

Event names:

onTransitionEnd

Properties:

string propertyNamestring pseudoElementfloat elapsedTime

Other Events

Event names:

onToggle