Drag Handle extension

Have you ever wanted to drag nodes around your editor? Well, we did too—so here’s an extension for that.

The DragHandle extension allows you to easily handle dragging nodes around in the editor. You can define custom render functions, placement, and more.

Install

npm install @tiptap/extension-drag-handle

Settings

render

Renders an element that is positioned with the floating-ui/dom package. This is the element that will be displayed as the handle when dragging a node around.

DragHandle.configure({
  render: () => {
    const element = document.createElement('div')

    // Use as a hook for CSS to insert an icon
    element.classList.add('custom-drag-handle')

    return element
  },
})

computePositionConfig

Configuration for position computation of the drag handle using the floating-ui/dom package. You can pass any options that are available in the floating-ui documentation.

Default: { placement: 'left-start', strategy: 'absolute' }

DragHandle.configure({
  computePositionConfig: {
    placement: 'left',
    strategy: 'fixed',
  },
})

getReferencedVirtualElement

A function that returns the virtual element for the drag handle. This is useful when the menu needs to be positioned relative to a specific DOM element.

Default: undefined

DragHandle.configure({
  getReferencedVirtualElement: () => {
    // Return a virtual element for custom positioning
    return null
  },
})

locked

Locks the draghandle in place and visibility. If the drag handle was visible, it will remain visible until unlocked. If it was hidden, it will remain hidden until unlocked.

Default: false

DragHandle.configure({
  locked: true,
})

onNodeChange

Returns a node or null when a node is hovered over. This can be used to highlight the node that is currently hovered over.

Default: undefined

DragHandle.configure({
  onNodeChange: ({ node, editor, pos }) => {
    if (!node) {
      selectedNode = null
      return
    }
    // Do something with the node
    selectedNode = node
  },
})

Commands

lockDragHandle()

Locks the draghandle in place and visibility. If the drag handle was visible, it will remain visible until unlocked. If it was hidden, it will remain hidden until unlocked.

This can be useful if you want to have a menu inside of the drag handle and want it to remain visible whether the drag handle is moused over or not.

editor.commands.lockDragHandle()

unlockDragHandle()

Unlocks the draghandle. Resets to default visibility and behavior.

editor.commands.unlockDragHandle()

toggleDragHandle()

Toggle draghandle lock state. If the drag handle is locked, it will be unlocked and vice versa.

editor.commands.toggleDragHandle()