DragHandle - Tiptap

The DragHandle extension adds a draggable handle to blocks in your editor, allowing users to reorder content by dragging. It uses Floating UI for intelligent positioning and supports nested content like list items and blockquotes.

Installation

npm install @tiptap/extension-drag-handle

Basic Usage

import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { DragHandle } from '@tiptap/extension-drag-handle'

const editor = new Editor({
  extensions: [
    StarterKit,
    DragHandle.configure({
      render() {
        const element = document.createElement('div')
        element.classList.add('drag-handle')
        element.innerHTML = '⋮⋮'
        return element
      },
    }),
  ],
})

Styling the Drag Handle

.drag-handle {
  position: absolute;
  cursor: grab;
  padding: 4px;
  color: #999;
  background: white;
  border: 1px solid #ddd;
  border-radius: 4px;
  user-select: none;
}

.drag-handle:hover {
  color: #333;
  background: #f5f5f5;
}

.drag-handle:active {
  cursor: grabbing;
}

Configuration Options

render

() => HTMLElement

required

Function that renders and returns the drag handle element.

DragHandle.configure({
  render() {
    const element = document.createElement('div')
    element.classList.add('drag-handle')
    element.innerHTML = `
      <svg width="10" height="10">
        <circle cx="5" cy="5" r="1" fill="currentColor"/>
        <circle cx="5" cy="2" r="1" fill="currentColor"/>
        <circle cx="5" cy="8" r="1" fill="currentColor"/>
      </svg>
    `
    return element
  },
})

computePositionConfig

ComputePositionConfig

Configuration for position computation using the Floating UI library. See Floating UI documentation for details.Default:

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

Example:

DragHandle.configure({
  render() { /* ... */ },
  computePositionConfig: {
    placement: 'right-start',
    strategy: 'fixed',
  },
})

getReferencedVirtualElement

() => VirtualElement | null

Function that returns a virtual element for positioning. Useful when the drag handle needs to be positioned relative to a specific DOM element.

DragHandle.configure({
  render() { /* ... */ },
  getReferencedVirtualElement: () => ({
    getBoundingClientRect: () => customElement.getBoundingClientRect(),
  }),
})

locked

boolean

Whether the drag handle is locked in place and visibility.Default: false

DragHandle.configure({
  render() { /* ... */ },
  locked: true, // Handle stays visible and in position
})

onNodeChange

function

Callback function called when a node is hovered over or unhovered.Parameters:

node: The hovered node (or null if unhovered)
editor: The editor instance

DragHandle.configure({
  render() { /* ... */ },
  onNodeChange: ({ node, editor }) => {
    if (node) {
      console.log('Hovering over:', node.type.name)
    } else {
      console.log('No longer hovering')
    }
  },
})

onElementDragStart

(e: DragEvent) => void

Callback fired when dragging starts.

DragHandle.configure({
  render() { /* ... */ },
  onElementDragStart: (e) => {
    console.log('Drag started')
    document.body.classList.add('is-dragging')
  },
})

onElementDragEnd

(e: DragEvent) => void

Callback fired when dragging ends.

DragHandle.configure({
  render() { /* ... */ },
  onElementDragEnd: (e) => {
    console.log('Drag ended')
    document.body.classList.remove('is-dragging')
  },
})

nested

boolean | NestedOptions

Enable drag handles for nested content like list items and blockquotes.Default: falseSimple enable:

DragHandle.configure({
  render() { /* ... */ },
  nested: true,
})

With configuration:

DragHandle.configure({
  render() { /* ... */ },
  nested: {
    allowedContainers: ['bulletList', 'orderedList'],
    edgeDetection: 'left',
    defaultRules: true,
  },
})

Nested Options:

nested.rules

DragHandleRule[]

Custom rules to determine which nodes are draggable. These run after the default rules.

nested: {
  rules: [{
    id: 'excludeCodeBlocks',
    evaluate: ({ node }) => {
      return node.type.name === 'codeBlock' ? 1000 : 0
    },
  }],
}

nested.defaultRules

boolean

Whether to include default rules for common cases like list items.Default: true

nested.allowedContainers

string[]

Restrict nested dragging to specific container types.

nested: {
  allowedContainers: ['bulletList', 'orderedList', 'blockquote'],
}

nested.edgeDetection

'left' | 'right' | 'both' | 'none'

Control when to prefer parent over nested node based on cursor position.

'left' (default): Prefer parent near left/top edges
'right': Prefer parent near right/top edges (for RTL)
'both': Prefer parent near any horizontal edge
'none': Disable edge detection

Or pass a config object:

nested: {
  edgeDetection: {
    edges: ['left', 'top'],
    threshold: 12,  // pixels from edge
    strength: 500,  // scoring strength
  },
}

Commands

lockDragHandle

command

Lock the drag handle in place and visibility.

editor.commands.lockDragHandle()

unlockDragHandle

command

Unlock the drag handle.

editor.commands.unlockDragHandle()

toggleDragHandle

command

Toggle the drag handle lock state.

editor.commands.toggleDragHandle()

Advanced Examples

Custom Drag Handle with Icon

DragHandle.configure({
  render() {
    const element = document.createElement('div')
    element.classList.add('custom-drag-handle')
    element.innerHTML = `
      <svg width="20" height="20" viewBox="0 0 20 20">
        <path d="M7 2a2 2 0 1 0 .001 4.001A2 2 0 0 0 7 2zm0 6a2 2 0 1 0 .001 4.001A2 2 0 0 0 7 8zm0 6a2 2 0 1 0 .001 4.001A2 2 0 0 0 7 14zm6-8a2 2 0 1 0-.001-4.001A2 2 0 0 0 13 6zm0 2a2 2 0 1 0 .001 4.001A2 2 0 0 0 13 8zm0 6a2 2 0 1 0 .001 4.001A2 2 0 0 0 13 14z" fill="currentColor"/>
      </svg>
    `
    return element
  },
})

Track Drag Events

DragHandle.configure({
  render() {
    const element = document.createElement('div')
    element.classList.add('drag-handle')
    element.innerHTML = '⋮⋮'
    return element
  },
  onElementDragStart: (e) => {
    console.log('Started dragging')
    // Add visual feedback
    document.body.classList.add('is-dragging')
  },
  onElementDragEnd: (e) => {
    console.log('Finished dragging')
    // Remove visual feedback
    document.body.classList.remove('is-dragging')
    // Track analytics
    analytics.track('block_reordered')
  },
  onNodeChange: ({ node }) => {
    if (node) {
      console.log('Hovering node:', node.type.name)
    }
  },
})

Enable Nested Dragging for Lists

DragHandle.configure({
  render() {
    const element = document.createElement('div')
    element.classList.add('drag-handle')
    element.innerHTML = '⋮⋮'
    return element
  },
  nested: {
    allowedContainers: ['bulletList', 'orderedList'],
    edgeDetection: 'left',
  },
})

Custom Rules for Nested Dragging

DragHandle.configure({
  render() { /* ... */ },
  nested: {
    rules: [
      {
        id: 'preferListItems',
        evaluate: ({ node }) => {
          // Prefer list items over lists
          if (node.type.name === 'listItem') return -100
          if (node.type.name === 'bulletList') return 100
          return 0
        },
      },
      {
        id: 'excludeCodeBlocks',
        evaluate: ({ node }) => {
          // Make code blocks undraggable
          if (node.type.name === 'codeBlock') return 1000
          return 0
        },
      },
    ],
    defaultRules: true, // Keep default rules
  },
})

Right-Side Placement (RTL)

DragHandle.configure({
  render() { /* ... */ },
  computePositionConfig: {
    placement: 'right-start',
    strategy: 'absolute',
  },
  nested: {
    edgeDetection: 'right', // Prefer parent near right edge
  },
})

Lock/Unlock Programmatically

const editor = new Editor({
  extensions: [
    StarterKit,
    DragHandle.configure({
      render() { /* ... */ },
    }),
  ],
})

// Lock handle during certain operations
function performSensitiveOperation() {
  editor.commands.lockDragHandle()
  
  // Do operation...
  
  editor.commands.unlockDragHandle()
}

// Toggle lock with button
document.querySelector('#toggle-drag').addEventListener('click', () => {
  editor.commands.toggleDragHandle()
})

React Integration

import { useEditor, EditorContent } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'
import { DragHandle } from '@tiptap/extension-drag-handle'
import { useRef } from 'react'

function Editor() {
  const dragHandleRef = useRef<HTMLDivElement>(null)
  
  const editor = useEditor({
    extensions: [
      StarterKit,
      DragHandle.configure({
        render() {
          const element = document.createElement('div')
          element.className = 'drag-handle'
          element.innerHTML = '⋮⋮'
          return element
        },
        onNodeChange: ({ node }) => {
          if (node) {
            console.log('Hovering:', node.type.name)
          }
        },
      }),
    ],
  })
  
  return (
    <div>
      <button onClick={() => editor?.commands.toggleDragHandle()}>
        Toggle Drag Handle Lock
      </button>
      <EditorContent editor={editor} />
    </div>
  )
}

Styling Examples

Animated Drag Handle

.drag-handle {
  position: absolute;
  cursor: grab;
  padding: 4px 6px;
  color: #999;
  background: white;
  border: 1px solid #e0e0e0;
  border-radius: 4px;
  transition: all 0.15s ease;
  opacity: 0;
}

/* Show on hover */
*:hover > .drag-handle {
  opacity: 1;
}

.drag-handle:hover {
  color: #333;
  background: #f5f5f5;
  transform: scale(1.1);
}

.drag-handle:active {
  cursor: grabbing;
  transform: scale(1);
}

/* When dragging */
body.is-dragging .drag-handle {
  opacity: 0.5;
}

Nested Content Styling

/* Different styles for nested items */
.ProseMirror li > .drag-handle {
  left: -30px;
}

.ProseMirror blockquote > .drag-handle {
  left: -35px;
  color: #666;
}

Source Code

View the source code on GitHub:

Documentation Index

​Installation

​Basic Usage

​Styling the Drag Handle

​Configuration Options

​Commands

​Advanced Examples

​Custom Drag Handle with Icon

​Track Drag Events

​Enable Nested Dragging for Lists

​Custom Rules for Nested Dragging

​Right-Side Placement (RTL)

​Lock/Unlock Programmatically

​React Integration

​Styling Examples

​Animated Drag Handle

​Nested Content Styling

​Source Code

Installation

Basic Usage

Styling the Drag Handle

Configuration Options

Commands

Advanced Examples

Custom Drag Handle with Icon

Track Drag Events

Enable Nested Dragging for Lists

Custom Rules for Nested Dragging

Right-Side Placement (RTL)

Lock/Unlock Programmatically

React Integration

Styling Examples

Animated Drag Handle

Nested Content Styling

Source Code