w3resource
React Tutorial

SyntheticEvent


Overview

Your event handlers will be passed instances of SyntheticEvent, a cross-browser wrapper around the browser's native event. It has the same interface as the browser's native event, including stopPropagation() and preventDefault(), except the events work identically across all browsers.

If you need the underlying browser event for some reasons, simply use the nativeEvent attribute to get it. Every SyntheticEvent object has the following attributes:

  • boolean bubbles
  • boolean cancelable
  • DOMEventTarget currentTarget
  • boolean defaultPrevented
  • number eventPhase
  • boolean isTrusted
  • DOMEvent nativeEvent
  • void preventDefault()
  • boolean isDefaultPrevented()
  • void stopPropagation()
  • boolean isPropagationStopped()
  • DOMEventTarget target
  • number timeStamp

Note:

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

Event Pooling

The SyntheticEvent is pooled. This means that the SyntheticEvent object will be reused and all properties will be nullified after the event callback has been invoked. This is for performance reasons. As such, you cannot access the event in an asynchronous way.

function onClick(event) {
  console.log(event); // => nullified object.
  console.log(event.type); // => "click"
  const eventType = event.type; // => "click"

  setTimeout(function() {
    console.log(event.type); // => null
    console.log(eventType); // => "click"
  }, 0);

  // Won't work. this.state.clickEvent will only contain null values.
  this.setState({clickEvent: event});

  // You can still export event properties.
  this.setState({eventType: event.type});
}

Note:

If you want to access the event properties in an asynchronous way, you should call event.persist() on the event, which will remove the synthetic event from the pool and allow references to the event to be retained by user code.

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, append Capture to the event name; for example, instead of using onClick, you would use onClickCapture to handle the click event in the capture phase.

Reference

Category Event names Properties
Clipboard Events onCopy onCut onPaste DOMDataTransfer clipboardData
Composition Events onCompositionEnd onCompositionStart onCompositionUpdate string data
Keyboard Events onKeyDown onKeyPress onKeyUp
  • boolean altKey
  • number charCode
  • vboolean ctrlKey
  • boolean getModifierState(key)
  • string key
  • number keyCode
  • string locale
  • number location
  • boolean metaKey
  • boolean repeat
  • boolean shiftKey
  • number which

The key property can take any of the values documented in the DOM Level 3 Events spec.

Focus Events

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

DOMEventTarget relatedTarget
Form Events onChange onInput onInvalid onSubmit
Mouse Events

onClick onContextMenu onDoubleClick onDrag onDragEnd onDragEnter onDragExit onDragLeave onDragOver onDragStart onDrop onMouseDown onMouseEnter onMouseLeave onMouseMove onMouseOut onMouseOver onMouseUp
The onMouseEnter and onMouseLeave events propagate from the element being left to the one being entered instead of ordinary bubbling and do not have a capture phase.

  • boolean altKey
  • number button
  • number buttons
  • number clientX
  • number clientY
  • boolean ctrlKey
  • boolean getModifierState(key)
  • boolean metaKey
  • number pageX
  • number pageY
  • DOMEventTarget relatedTarget
  • number screenX
  • number screenY
  • boolean shiftKey
Pointer Events

onPointerDown onPointerMove onPointerUp onPointerCancel onGotPointerCapture onLostPointerCapture onPointerEnter onPointerLeave onPointerOver onPointerOut

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

As defined in the W3 spec, pointer events extend Mouse Events with the following properties:
  • number pointerId
  • number width
  • number height
  • number pressure
  • number tangentialPressure
  • number tiltX
  • number tiltY
  • number twist
  • string pointerType
  • boolean 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 of react-dom.
If your application requires pointer events, we recommend adding a third party pointer event polyfill.

Selection Events onSelect
Touch Events onTouchCancel onTouchEnd onTouchMove onTouchStart
  • boolean altKey
  • DOMTouchList changedTouches
  • boolean ctrlKey
  • boolean getModifierState(key)
  • boolean metaKey
  • boolean shiftKey
  • DOMTouchList targetTouches
  • DOMTouchList touches
UI Events onScroll
  • number detail
  • DOMAbstractView view
Wheel Events onWheel
  • number deltaMode
  • number deltaX
  • number deltaY
  • number deltaZ
Media Events onAbort onCanPlay onCanPlayThrough onDurationChange onEmptied onEncrypted onEnded onError onLoadedData onLoadedMetadata onLoadStart onPause onPlay onPlaying onProgress onRateChange onSeeked onSeeking onStalled onSuspend onTimeUpdate onVolumeChange onWaiting
Image Events onLoad onError
Animation Events onAnimationStart onAnimationEnd onAnimationIteration
  • string animationName
  • string pseudoElement
  • float elapsedTime
Transition Events onTransitionEnd
  • string propertyName
  • string pseudoElement
  • float elapsedTime
Other Events onToggle