--- title: Drag & Drop description: Drag and drop blocks to reorganize content within the editor. docs: - route: https://pro.platejs.org/docs/examples/dnd title: Plus - route: /docs/components/block-draggable title: Block Draggable --- ## 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`](/docs/components/block-draggable) UI component. - [`BlockDraggable`](/docs/components/block-draggable): Renders drag handles and drop indicators for blocks. ### Add Kit ```tsx import { createPlateEditor } from 'platejs/react'; import { DndKit } from '@/components/editor/plugins/dnd-kit'; const editor = createPlateEditor({ plugins: [ // ...otherPlugins, ...DndKit, ], }); ``` ## Manual Usage ### Installation ```bash npm install @platejs/dnd react-dnd react-dnd-html5-backend ``` ### Add Plugin ```tsx 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: ```tsx import { DndProvider } from 'react-dnd'; import { HTML5Backend } from 'react-dnd-html5-backend'; import { DndPlugin } from '@platejs/dnd'; DndPlugin.configure({ render: { aboveSlate: ({ children }) => ( {children} ), }, }); ``` - `render.aboveNodes`: Assigns [`BlockDraggable`](/docs/components/block-draggable) 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: ```tsx 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 }) => ( {children} ), }, }); ``` - `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. 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. ID of the target element. Object containing the dropped files. The editor instance. Path where files should be inserted. 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. The ID of the block to be focused. ### `getBlocksWithId` Returns an array of blocks that have an ID. The options for getting node entries. Array of blocks that have an ID. ### `selectBlockById` Selects a block by its ID. 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. 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. 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`. 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. The element to make draggable. Orientation of drag and drop. - **Default:** `'vertical'` Type of drag item. - **Default:** `'block'` Handler called when element is dropped. 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. 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. Element ID to show drop line for. - **Default:** Current element ID Filter drop lines by orientation. - **Default:** `'vertical'` Current drop line direction.