Drag & Drop

PreviousNext

Drag and drop blocks to reorganize content within the editor.

PlusBlock Draggable
Loading...

Features

  • Drag and drop blocks for content movement and insertion within the editor.
  • Automatic scrolling when dragging blocks near viewport edges.
  • File drop support for inserting media blocks.
  • Visual drop indicators and drag handles.

Kit Usage

Installation

The fastest way to add drag and drop functionality is with the DndKit, which includes the pre-configured DndPlugin along with React DnD setup and the BlockDraggable UI component.

  • BlockDraggable: Renders drag handles and drop indicators for blocks.

Add Kit

import { createPlateEditor } from 'platejs/react';
import { DndKit } from '@/components/editor/plugins/dnd-kit';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...DndKit,
  ],
});

Manual Usage

Installation

pnpm add @platejs/dnd react-dnd react-dnd-html5-backend

Add Plugin

import { DndPlugin } from '@platejs/dnd';
import { createPlateEditor } from 'platejs/react';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    DndPlugin,
  ],
});

Configure Plugin

Configure drag and drop with a draggable component and DnD provider:

import { DndProvider } from 'react-dnd';
import { HTML5Backend } from 'react-dnd-html5-backend';
import { DndPlugin } from '@platejs/dnd';
 
DndPlugin.configure({
  render: {
    aboveSlate: ({ children }) => (
      <DndProvider backend={HTML5Backend}>{children}</DndProvider>
    ),
  },
});
  • render.aboveNodes: Assigns BlockDraggable to render drag handles above blocks.
  • render.aboveSlate: Wraps the editor with DndProvider and HTML5Backend. Remove this if you already have DndProvider in your React tree.

Advanced Configuration

Add automatic scrolling and file drop handling:

import { DndPlugin } from '@platejs/dnd';
import { PlaceholderPlugin } from '@platejs/media/react';
 
DndPlugin.configure({
  options: {
    enableScroller: true,
    onDropFiles: ({ dragItem, editor, target }) => {
      editor
        .getTransforms(PlaceholderPlugin)
        .insert.media(dragItem.files, { at: target, nextBlock: false });
    },
  },
  render: {
    aboveNodes: BlockDraggable,
    aboveSlate: ({ children }) => (
      <DndProvider backend={HTML5Backend}>{children}</DndProvider>
    ),
  },
});
  • enableScroller: Enables automatic scrolling when dragging blocks near the viewport edges.
  • onDropFiles: Handles file drops by inserting them as media blocks at the target location.

Plugins

DndPlugin

Plugin for drag and drop functionality within the editor.

Options

  • enableScroller optional boolean

    Enables automatic scrolling when dragging blocks near viewport edges.

    • Default: false

  • scrollerProps optional Partial<ScrollerProps>

    Props for the Scroller component when enableScroller is true.

  • onDropFiles optional function

    Handler for file drop events.

  • dropTarget optional { id: string | null; line: DropLineDirection }

    The current drop target state containing both the target element id and drop line direction.

API

focusBlockStartById

Selects the start of a block by ID and focuses the editor.

Parameters

Collapse all

  • id string

    The ID of the block to be focused.

getBlocksWithId

Returns an array of blocks that have an ID.

OptionsEditorNodesOptions

    The options for getting node entries.

ReturnsNodeEntry[]

    Array of blocks that have an ID.

selectBlockById

Selects a block by its ID.

Parameters

Collapse all

  • id string

    The ID of the block to select.

Hooks

useDndNode

A custom hook that combines the useDragNode and useDropNode hooks to enable dragging and dropping of a node from the editor. It provides a default preview for the dragged node, which can be customized or disabled.

OptionsUseDndNodeOptions

Collapse all

  • element TElement

    The node to be dragged.

  • type optional string

    The type of drag item.

    • Default: 'block'

  • nodeRef any

    The ref of the node to be dragged.

  • orientation optional 'horizontal' | 'vertical'

    The orientation of drag and drop.

    • Default: 'vertical'

  • canDropNode optional (args: { dragEntry: NodeEntry; dragItem: DragItemNode; dropEntry: NodeEntry; editor: PlateEditor }) => boolean

    Callback to determine if a node can be dropped at the current location.

  • preview optional previewOptions

    The preview options for the dragged node.

  • drag optional dragOptions

    The drag options for the dragged node.

  • drop optional dropOptions

    The drop options for the dragged node.

  • onDropHandler optional string

    Handler called when the node is dropped.

Returnsobject

Collapse all

  • isDragging boolean

    Whether the node is currently being dragged.

  • isOver boolean

    Whether the dragged node is over a drop target.

  • dragRef ConnectDragSource

    Drag reference for the draggable element.

useDragNode

A custom hook that enables dragging of a node from the editor using the useDrag hook from react-dnd.

OptionsUseDragNodeOptions

Collapse all

  • element TElement

    The node to be dragged.

  • item optional DragObject | DragObjectFactory<DragObject>

    Drag object or factory function that returns it.

useDraggable

A custom hook that enables draggable behavior for a given element. It provides a preview for the element, which can be customized or disabled.

Optionsobject

Collapse all

  • element TElement

    The element to make draggable.

  • orientation optional 'horizontal' | 'vertical'

    Orientation of drag and drop.

    • Default: 'vertical'

  • type optional string

    Type of drag item.

    • Default: 'block'

  • onDropHandler optional function

    Handler called when element is dropped.

Returnsobject

Collapse all

  • handleRef (element: Element | React.ReactElement | React.RefObject<any> | null) => void

    Drag source connector function.

  • isDragging boolean

    Whether element is being dragged.

  • previewRef React.RefObject<HTMLDivElement>

    Reference to draggable element.

useDropNode

A custom hook that enables dropping a node on the editor. It uses the useDrop hook from react-dnd to handle the drop behavior.

OptionsUseDropNodeOptions

Collapse all

  • nodeRef any

    Reference to the node being dragged.

  • element TElement

    The node to which the drop line is attached.

  • dropLine string

    Current value of the drop line.

  • onChangeDropLine function

    Callback when drop line changes.

  • onDropHandler object

    Callback that intercepts drop handling.

    • Returns true to prevent default behavior
    • Returns false to run default behavior after

useDropLine

Returns the current drop line state for an element.

Optionsobject

Collapse all

  • id optional string

    Element ID to show drop line for.

    • Default: Current element ID

  • orientation optional 'horizontal' | 'vertical'

    Filter drop lines by orientation.

    • Default: 'vertical'

Returnsobject

Collapse all

  • dropLine 'top' | 'bottom' | 'left' | 'right' | ''

    Current drop line direction.

拖拽功能查找