Jittery movement when draggable uses nodeRef, smooth movement when using handle

[viveleroi]

Looks like nodeRef causes jittery movement when the handle is not a direct ancestor. For example, using the nodeRef example from the README and adding a div wrapping the target causes this issue.

We're updating draggable modal windows to use nodeRef props to avoid the console warning about findDOMNode being deprecated. Previously, we had handle set to a DOM class name and that exact class name assigned to an element inside the element.

<Draggable nodeRef={dragRef}>
  <div>
     <header className={clsx(styles.header, styles[uiVariant])} ref={dragRef}>/* content */</header>
  </div>
</Draggable>

With the handle approach, the movement when dragging and item was smooth and we had no issues. With the nodeRef, it's incredibly jittery. We normally have bounds and onDragStart methods but I removed those for testing and the jitter persists.

[troywoy]

Minimal reproduction: https://codesandbox.io/p/sandbox/nlpcgq

[ykant]

"next": "^15.0.0", "react-draggable": "^4.4.6", "react": "^18.3.1", "react-dom": "^18.3.1",

I met the same situation, fixed by adding offsetParent={document.body}. Wish can help

[STRML]

This was generated by AI during triage.

Triage (ready-for-human)

Jitter happens when nodeRef points at an element inside the child that <Draggable> transforms. Drag offsets are measured against nodeRef.current.offsetParent. When that node sits inside the transformed element, the offset parent moves with the drag, and each move event is measured against a moving origin. That explains why offsetParent={document.body} fixes it (see this comment).

<Draggable nodeRef={ref}>
  <div>            <- gets the transform, moves
    <header ref>   <- offsetParent is the moving div -> jitter

Needs a maintainer decision before handoff:

Option	Cost
Document that nodeRef must point at the direct child (use handle for an inner grip)	Docs only, but existing users keep hitting it
Dev warning when nodeRef.current is not the element that receives the transform	Small, catches it at mount
Measure against the transformed child's offset parent instead of the ref'd node's	Behavior change for DraggableCore users