or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

auto-scrolling.mdcomponent-utilities.mddrag-drop-hooks.mdeditor-transforms.mdindex.mdplugin-configuration.mdutility-functions.md
tile.json

tessl/npm-udecode--plate-dnd

React drag and drop plugin for Plate rich-text editor enabling block rearrangement and file drops

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@udecode/plate-dnd@49.0.x

To install, run

npx @tessl/cli install tessl/npm-udecode--plate-dnd@49.0.0

index.mddocs/

Plate DnD

The @udecode/plate-dnd package provides comprehensive drag-and-drop functionality for the Plate rich-text editor. It enables users to rearrange editor blocks through intuitive drag-and-drop interactions, with features including visual drop indicators, automatic viewport scrolling during drag operations, customizable drag handles, and support for file drops to insert media content. The plugin integrates seamlessly with React DnD backend and provides hooks for managing drag states, drop zones, and node interactions.

Package Information

  • Package Name: @udecode/plate-dnd
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @udecode/plate-dnd

Core Imports

import { DndPlugin, useDndNode, useDraggable, useDropLine } from "@udecode/plate-dnd";

For CommonJS:

const { DndPlugin, useDndNode, useDraggable, useDropLine } = require("@udecode/plate-dnd");

Basic Usage

import { DndPlugin, useDndNode } from "@udecode/plate-dnd";
import { createPlateEditor } from "@udecode/plate/react";

// Configure the plugin
const editor = createPlateEditor({
  plugins: [
    DndPlugin.configure({
      options: {
        enableScroller: true,
        onDropFiles: ({ id, dragItem, editor, target }) => {
          // Handle file drops to insert media
          console.log('File dropped:', dragItem.files);
        }
      }
    })
  ]
});

// Use in a block component
function DraggableBlock({ element, children }) {
  const { dragRef, isDragging, isOver } = useDndNode({
    element,
    orientation: 'vertical'
  });

  return (
    <div 
      ref={dragRef}
      style={{ opacity: isDragging ? 0.5 : 1 }}
    >
      {children}
    </div>
  );
}

Architecture

The @udecode/plate-dnd package is built around several key components:

  • Plugin System: Core DndPlugin integrating with Plate's plugin architecture
  • React DnD Integration: Built on react-dnd for robust drag-and-drop behavior
  • Hook-based API: Composable hooks for different aspects of drag-and-drop
  • Auto-scrolling: Smart viewport scrolling during drag operations
  • Type Safety: Full TypeScript support with comprehensive type definitions
  • File Drop Support: Native browser file drop handling for media insertion

Capabilities

Plugin Configuration

The core DndPlugin that integrates drag-and-drop functionality into Plate editors, with configurable options for behavior customization.

export const DndPlugin: PlatePlugin<DndConfig>;

export type DndConfig = PluginConfig<
  'dnd',
  {
    draggingId?: string | null;
    dropTarget?: {
      id: string | null;
      line: DropLineDirection;
    };
    enableScroller?: boolean;
    isDragging?: boolean;
    scrollerProps?: Partial<ScrollerProps>;
    onDropFiles?: (props: {
      id: string;
      dragItem: FileDragItemNode;
      editor: PlateEditor;
      monitor: DropTargetMonitor<DragItemNode, unknown>;
      nodeRef: any;
      target?: Path;
    }) => void;
  }
>;

export const DRAG_ITEM_BLOCK = 'block';

Plugin Configuration

Drag and Drop Hooks

React hooks for implementing drag-and-drop behavior on editor nodes, with support for both dragging and dropping functionality.

export function useDndNode(options: UseDndNodeOptions): {
  dragRef: ConnectDragSource;
  isDragging: boolean;
  isOver: boolean;
};

export function useDragNode(
  editor: PlateEditor,
  options: UseDragNodeOptions
): [{ isDragging: boolean }, ConnectDragSource, ConnectDragPreview];

export function useDropNode(
  editor: PlateEditor,
  options: UseDropNodeOptions
): [{ isOver: boolean }, ConnectDropTarget];

Drag and Drop Hooks

Component Utilities

Pre-built components and hooks for common drag-and-drop UI patterns including draggable elements and drop line indicators.

export function useDraggable(props: UseDndNodeOptions): DraggableState;

export function useDropLine(options?: {
  id?: string;
  orientation?: 'horizontal' | 'vertical';
}): {
  dropLine?: DropLineDirection;
};

export type DraggableState = {
  isDragging: boolean;
  previewRef: React.RefObject<HTMLDivElement | null>;
  handleRef: (elementOrNode: Element | React.ReactElement<any> | React.RefObject<any> | null) => void;
};

Component Utilities

Auto-scrolling Components

Components that provide automatic viewport scrolling when dragging near screen edges, enhancing user experience during drag operations.

export function DndScroller(props: Partial<ScrollerProps>): JSX.Element;

export function Scroller(props: ScrollerProps): JSX.Element;

export function ScrollArea({
  placement,
  containerRef,
  enabled,
  height,
  minStrength,
  scrollAreaProps,
  strengthMultiplier,
  zIndex
}: ScrollAreaProps): JSX.Element | null;

Auto-scrolling Components

Editor Transforms

Functions for manipulating editor state during drag-and-drop operations, including block selection, movement, and focus management.

export function selectBlocksBySelectionOrId(editor: PlateEditor, id: string): void;

export function selectBlockById(editor: Editor, id: string): void;

export function removeBlocksAndFocus<E extends Editor = Editor>(
  editor: E,
  options: EditorNodesOptions<ValueOf<E>>
): void;

export function focusBlockStartById(editor: Editor, id: string): void;

export function onDropNode(
  editor: PlateEditor,
  options: OnDropNodeOptions
): void;

Editor Transforms

Utility Functions

Helper functions for calculating drop directions, handling hover states, and determining valid drop operations.

export function getHoverDirection(options: GetHoverDirectionOptions): string;

export function getNewDirection(
  previousDir: string,
  dir?: string
): DropLineDirection | undefined;

export function getBlocksWithId<E extends Editor>(
  editor: E,
  options: EditorNodesOptions<ValueOf<E>>
): NodeEntry<TElement>[];

Utility Functions

Types

export type DragItemNode = ElementDragItemNode | FileDragItemNode;

export type DropDirection = 'bottom' | 'left' | 'right' | 'top' | undefined;

export type DropLineDirection = '' | 'bottom' | 'left' | 'right' | 'top';

export interface ElementDragItemNode {
  id: string;
  element: TElement;
  [key: string]: unknown;
}

export interface FileDragItemNode {
  dataTransfer: DataTransfer[];
  files: FileList;
  items: DataTransferItemList;
}