Common components (e.g. <div>)·续3

Caveats

  • You cannot pass both children and dangerouslySetInnerHTML at the same time.
  • Some events (like onAbort and onLoad) don't bubble in the browser, but bubble in React.

ref callback function

Instead of a ref object (like the one returned by useRef), you may pass a function to the ref attribute.

<div ref={(node) => {
  console.log('Attached', node);

return () => {
    console.log('Clean up', node)
  }
}}>

See an example of using the ref callback.

When the <div> DOM node is added to the screen, React will call your ref callback with the DOM node as the argument. When that <div> DOM node is removed, React will call your the cleanup function returned from the callback.

React will also call your ref callback whenever you pass a different ref callback. In the above example, (node) => { ... } is a different function on every render. When your component re-renders, the previous function will be called with null as the argument, and the next function will be called with the DOM node.

Parameters

  • node: A DOM node. React will pass you the DOM node when the ref gets attached. Unless you pass the same function reference for the ref callback on every render, the callback will get temporarily cleanup and re-create during every re-render of the component.

[!NOTE]

React 19 added cleanup functions for ref callbacks.

To support backwards compatibility, if a cleanup function is not returned from the ref callback, node will be called with null when the ref is detached. This behavior will be removed in a future version.

Returns

  • optional cleanup function: When the ref is detached, React will call the cleanup function. If a function is not returned by the ref callback, React will call the callback again with null as the argument when the ref gets detached. This behavior will be removed in a future version.

Caveats

  • When Strict Mode is on, React will run one extra development-only setup+cleanup cycle before the first real setup. This is a stress-test that ensures that your cleanup logic "mirrors" your setup logic and that it stops or undoes whatever the setup is doing. If this causes a problem, implement the cleanup function.
  • When you pass a different ref callback, React will call the previous callback's cleanup function if provided. If no cleanup function is defined, the ref callback will be called with null as the argument. The next function will be called with the DOM node.

React event object

Your event handlers will receive a React event object. It is also sometimes known as a "synthetic event".

<button onClick={e => {
  console.log(e); // React event object
}} />

It conforms to the same standard as the underlying DOM events, but fixes some browser inconsistencies.

Some React events do not map directly to the browser's native events. For example in onMouseLeave, e.nativeEvent will point to a mouseout event. The specific mapping is not part of the public API and may change in the future. If you need the underlying browser event for some reason, read it from e.nativeEvent.

Properties

React event objects implement some of the standard Event properties:

  • bubbles: A boolean. Returns whether the event bubbles through the DOM.
  • cancelable: A boolean. Returns whether the event can be canceled.
  • currentTarget: A DOM node. Returns the node to which the current handler is attached in the React tree.
  • defaultPrevented: A boolean. Returns whether preventDefault was called.
  • eventPhase: A number. Returns which phase the event is currently in.
  • isTrusted: A boolean. Returns whether the event was initiated by user.
  • target: A DOM node. Returns the node on which the event has occurred (which could be a distant child).
  • timeStamp: A number. Returns the time when the event occurred.

Additionally, React event objects provide these properties:

  • nativeEvent: A DOM Event. The original browser event object.

Methods

React event objects implement some of the standard Event methods:

Additionally, React event objects provide these methods:

  • isDefaultPrevented(): Returns a boolean value indicating whether preventDefault was called.
  • isPropagationStopped(): Returns a boolean value indicating whether stopPropagation was called.
  • persist(): Not used with React DOM. With React Native, call this to read event's properties after the event.
  • isPersistent(): Not used with React DOM. With React Native, returns whether persist has been called.

Caveats

  • The values of currentTarget, eventPhase, target, and type reflect the values your React code expects. Under the hood, React attaches event handlers at the root, but this is not reflected in React event objects. For example, e.currentTarget may not be the same as the underlying e.nativeEvent.currentTarget. For polyfilled events, e.type (React event type) may differ from e.nativeEvent.type (underlying type).

AnimationEvent handler function

An event handler type for the CSS animation events.

<div
  onAnimationStart={e => console.log('onAnimationStart')}
  onAnimationIteration={e => console.log('onAnimationIteration')}
  onAnimationEnd={e => console.log('onAnimationEnd')}
/>

Parameters


ClipboardEvent handler function

An event handler type for the Clipboard API events.