Drag & Drop

PreviousNext

Drag and drop blocks to reorganize content within the editor.

PlusBlock Draggable
Loading...
Files
components/demo.tsx
'use client';

import * as React from 'react';

import { Plate, usePlateEditor } from 'platejs/react';

import { EditorKit } from '@/components/editor/editor-kit';
import { Editor, EditorContainer } from '@/components/ui/editor';

import { DEMO_VALUES } from './values/demo-values';

export default function Demo({ id }: { id: string }) {
  const editor = usePlateEditor({
    plugins: EditorKit,
    value: DEMO_VALUES[id],
  });

  return (
    <Plate editor={editor}>
      <EditorContainer variant="demo">
        <Editor />
      </EditorContainer>
    </Plate>
  );
}

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.

'use client';
 
import { DndProvider } from 'react-dnd';
import { HTML5Backend } from 'react-dnd-html5-backend';
 
import { DndPlugin } from '@platejs/dnd';
import { PlaceholderPlugin } from '@platejs/media/react';
 
import { BlockDraggable } from '@/components/ui/block-draggable';
 
export const DndKit = [
  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>
      ),
    },
  }),
];
  • 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

Collapse all

    Enables automatic scrolling when dragging blocks near viewport edges.

    • Default: false

    Props for the Scroller component when enableScroller is true.

    Handler for file drop events.

    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

    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

    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

    The node to be dragged.

    The type of drag item.

    • Default: 'block'

    The ref of the node to be dragged.

    The orientation of drag and drop.

    • Default: 'vertical'

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

    The preview options for the dragged node.

    The drag options for the dragged node.

    The drop options for the dragged node.

    Handler called when the node is dropped.

Returnsobject

Collapse all

    Whether the node is currently being dragged.

    Whether the dragged node is over a drop target.

    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

    The node to be dragged.

    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

    The element to make draggable.

    Orientation of drag and drop.

    • Default: 'vertical'

    Type of drag item.

    • Default: 'block'

    Handler called when element is dropped.

Returnsobject

Collapse all

    Drag source connector function.

    Whether element is being dragged.

    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

    Reference to the node being dragged.

    The node to which the drop line is attached.

    Current value of the drop line.

    Callback when drop line changes.

    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

    Element ID to show drop line for.

    • Default: Current element ID

    Filter drop lines by orientation.

    • Default: 'vertical'

Returnsobject

Collapse all

    Current drop line direction.

Cursor OverlayTabbable