This reference guide documents the SyntheticEvent
wrapper that forms part of React’s Event System. See the Handling Events guide to learn more.
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 find that you need the underlying browser event for some reason, 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 string type
Note:
As of v0.14, returning
false
from an event handler will no longer stop event propagation. Instead,e.stopPropagation()
ore.preventDefault()
should be triggered manually, as appropriate.
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.
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.
Event names:
onCopy onCut onPaste
Properties:
DOMDataTransfer clipboardData
Event names:
onCompositionEnd onCompositionStart onCompositionUpdate
Properties:
string data
Event names:
onKeyDown onKeyPress onKeyUp
Properties:
boolean altKey number charCode boolean 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.
Event names:
onFocus onBlur
These focus events work on all elements in the React DOM, not just form elements.
Properties:
DOMEventTarget relatedTarget
Event names:
onChange onInput onInvalid onSubmit
For more information about the onChange event, see Forms.
Event names:
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.
Properties:
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
Event names:
onSelect
Event names:
onTouchCancel onTouchEnd onTouchMove onTouchStart
Properties:
boolean altKey DOMTouchList changedTouches boolean ctrlKey boolean getModifierState(key) boolean metaKey boolean shiftKey DOMTouchList targetTouches DOMTouchList touches
Event names:
onScroll
Properties:
number detail DOMAbstractView view
Event names:
onWheel
Properties:
number deltaMode number deltaX number deltaY number deltaZ
Event names:
onAbort onCanPlay onCanPlayThrough onDurationChange onEmptied onEncrypted onEnded onError onLoadedData onLoadedMetadata onLoadStart onPause onPlay onPlaying onProgress onRateChange onSeeked onSeeking onStalled onSuspend onTimeUpdate onVolumeChange onWaiting
Event names:
onLoad onError
Event names:
onAnimationStart onAnimationEnd onAnimationIteration
Properties:
string animationName string pseudoElement float elapsedTime
Event names:
onTransitionEnd
Properties:
string propertyName string pseudoElement float elapsedTime
Event names:
onToggle
© 2013–present Facebook Inc.
Licensed under the Creative Commons Attribution 4.0 International Public License.
https://reactjs.org/docs/events.html