Skip to content

Block handle

Block handles are floating controls that appear in the gutter next to whichever block currently contains the cursor or pointer. Use them to let users insert new blocks (+ button) or reorder existing ones (drag handle).

'use client'

import 'prosekit/basic/style.css'
import 'prosekit/basic/typography.css'

import { createEditor, type NodeJSON } from 'prosekit/core'
import { ProseKit } from 'prosekit/react'
import { useMemo } from 'react'

import { sampleContent } from '../../sample/sample-doc-block-handle'
import { BlockHandle } from '../../ui/block-handle'
import { DropIndicator } from '../../ui/drop-indicator'

import { defineExtension } from './extension'

interface EditorProps {
  initialContent?: NodeJSON
}

export default function Editor(props: EditorProps) {
  const defaultContent = props.initialContent ?? sampleContent
  const editor = useMemo(() => {
    const extension = defineExtension()
    return createEditor({ extension, defaultContent })
  }, [defaultContent])

  return (
    <ProseKit editor={editor}>
      <div className="box-border h-full w-full min-h-36 overflow-y-hidden overflow-x-hidden rounded-md border border-solid border-gray-200 dark:border-gray-700 shadow-sm flex flex-col bg-[canvas] text-black dark:text-white">
        <div className="relative w-full flex-1 box-border overflow-y-auto">
          <div ref={editor.mount} className="ProseMirror box-border min-h-full px-[max(4rem,calc(50%-20rem))] py-8 outline-hidden outline-0 [&_span[data-mention=user]]:text-blue-500 [&_span[data-mention=tag]]:text-violet-500"></div>
          <BlockHandle />
          <DropIndicator />
        </div>
      </div>
    </ProseKit>
  )
}

import { defineBasicExtension } from 'prosekit/basic'
import { union } from 'prosekit/core'

import { defineCodeBlockView } from '../../ui/code-block-view'

export function defineExtension() {
  return union([defineBasicExtension(), defineCodeBlockView()])
}

export type EditorExtension = ReturnType<typeof defineExtension>

export { default as ExampleEditor } from './editor'

import type { NodeJSON } from 'prosekit/core'

export const sampleContent: NodeJSON = {
  type: 'doc',
  content: [
    {
      type: 'heading',
      attrs: {
        level: 1,
      },
      content: [
        {
          type: 'text',
          text: 'Drag and Drop Demo',
        },
      ],
    },
    {
      type: 'paragraph',
      content: [
        {
          type: 'text',
          text: 'Try dragging any paragraph or heading by clicking on the handle that appears on the left when you hover over it.',
        },
      ],
    },
    {
      type: 'heading',
      attrs: {
        level: 2,
      },
      content: [
        {
          type: 'text',
          text: 'Getting Started',
        },
      ],
    },
    {
      type: 'paragraph',
      content: [
        {
          type: 'text',
          text: 'Hover over any block to see the drag handle appear. Click and drag to reorder content.',
        },
      ],
    },
    {
      type: 'paragraph',
      content: [
        {
          type: 'text',
          text: 'This paragraph can be moved above or below other blocks.',
        },
      ],
    },
    {
      type: 'heading',
      attrs: {
        level: 2,
      },
      content: [
        {
          type: 'text',
          text: 'Different Block Types',
        },
      ],
    },
    {
      type: 'paragraph',
      content: [
        {
          type: 'text',
          text: 'You can drag paragraphs, headings, lists, code blocks, and more.',
        },
      ],
    },
    {
      type: 'heading',
      attrs: {
        level: 3,
      },
      content: [
        {
          type: 'text',
          text: 'Lists Work Too',
        },
      ],
    },
    {
      type: 'list',
      attrs: {
        kind: 'bullet',
        order: null,
        checked: false,
        collapsed: false,
      },
      content: [
        {
          type: 'paragraph',
          content: [
            {
              type: 'text',
              text: 'This entire list can be dragged',
            },
          ],
        },
      ],
    },
    {
      type: 'list',
      attrs: {
        kind: 'bullet',
        order: null,
        checked: false,
        collapsed: false,
      },
      content: [
        {
          type: 'paragraph',
          content: [
            {
              type: 'text',
              text: 'Individual list items stay together',
            },
          ],
        },
      ],
    },
    {
      type: 'list',
      attrs: {
        kind: 'bullet',
        order: null,
        checked: false,
        collapsed: false,
      },
      content: [
        {
          type: 'paragraph',
          content: [
            {
              type: 'text',
              text: 'Try moving this list around',
            },
          ],
        },
      ],
    },
    {
      type: 'list',
      attrs: {
        kind: 'ordered',
        order: null,
        checked: false,
        collapsed: false,
      },
      content: [
        {
          type: 'paragraph',
          content: [
            {
              type: 'text',
              text: 'Ordered lists also support dragging',
            },
          ],
        },
      ],
    },
    {
      type: 'list',
      attrs: {
        kind: 'ordered',
        order: null,
        checked: false,
        collapsed: false,
      },
      content: [
        {
          type: 'paragraph',
          content: [
            {
              type: 'text',
              text: 'The numbering updates automatically',
            },
          ],
        },
      ],
    },
    {
      type: 'list',
      attrs: {
        kind: 'ordered',
        order: null,
        checked: false,
        collapsed: false,
      },
      content: [
        {
          type: 'paragraph',
          content: [
            {
              type: 'text',
              text: 'Drag this list to see it in action',
            },
          ],
        },
      ],
    },
    {
      type: 'heading',
      attrs: {
        level: 3,
      },
      content: [
        {
          type: 'text',
          text: 'Code Blocks',
        },
      ],
    },
    {
      type: 'paragraph',
      content: [
        {
          type: 'text',
          text: 'Even code blocks can be moved:',
        },
      ],
    },
    {
      type: 'codeBlock',
      attrs: {
        language: 'javascript',
      },
      content: [
        {
          type: 'text',
          text: '// This code block can be dragged\nfunction dragAndDrop() {\n  return "Easy to rearrange!"\n}',
        },
      ],
    },
    {
      type: 'heading',
      attrs: {
        level: 2,
      },
      content: [
        {
          type: 'text',
          text: 'Nested Content',
        },
      ],
    },
    {
      type: 'blockquote',
      content: [
        {
          type: 'paragraph',
          content: [
            {
              type: 'text',
              text: 'This blockquote can be moved as a single unit.',
            },
          ],
        },
        {
          type: 'blockquote',
          content: [
            {
              type: 'paragraph',
              content: [
                {
                  type: 'text',
                  text: 'Nested blockquotes move together with their parent.',
                },
              ],
            },
          ],
        },
      ],
    },
    {
      type: 'heading',
      attrs: {
        level: 2,
      },
      content: [
        {
          type: 'text',
          text: 'Try It Yourself',
        },
      ],
    },
    {
      type: 'paragraph',
      content: [
        {
          type: 'text',
          text: 'Practice by moving this paragraph to the top of the document.',
        },
      ],
    },
    {
      type: 'paragraph',
      content: [
        {
          type: 'text',
          text: 'Or drag this one to between the headings above.',
        },
      ],
    },
    {
      type: 'paragraph',
      content: [
        {
          type: 'text',
          text: 'The drag handles make it easy to reorganize your content exactly how you want it.',
        },
      ],
    },
  ],
}

'use client'

import { BlockHandleAdd, BlockHandleDraggable, BlockHandlePopup, BlockHandlePositioner, BlockHandleRoot } from 'prosekit/react/block-handle'

interface Props {
  dir?: 'ltr' | 'rtl'
}

export default function BlockHandle(props: Props) {
  return (
    <BlockHandleRoot>
      <BlockHandlePositioner
        placement={props.dir === 'rtl' ? 'right' : 'left'}
        className="block overflow-visible w-min h-min z-50 ease-out transition-transform duration-100 motion-reduce:transition-none"
      >
        <BlockHandlePopup className="flex box-border origin-(--transform-origin) transition-[opacity,scale] transition-discrete motion-reduce:transition-none duration-100 data-[state=closed]:duration-150 data-[state=closed]:opacity-0 starting:opacity-0 data-[state=closed]:scale-95 starting:scale-95">
          <BlockHandleAdd className="h-6 w-6 cursor-pointer flex items-center box-border justify-center hover:bg-gray-100 dark:hover:bg-gray-800 rounded-sm text-gray-500/50 dark:text-gray-400/50">
            <div className="i-lucide-plus size-5 block" />
          </BlockHandleAdd>
          <BlockHandleDraggable className="h-6 w-5 cursor-grab flex items-center box-border justify-center hover:bg-gray-100 dark:hover:bg-gray-800 rounded-sm text-gray-500/50 dark:text-gray-400/50">
            <div className="i-lucide-grip-vertical size-5 block" />
          </BlockHandleDraggable>
        </BlockHandlePopup>
      </BlockHandlePositioner>
    </BlockHandleRoot>
  )
}

export { default as BlockHandle } from './block-handle'

'use client'

import type { CodeBlockAttrs } from 'prosekit/extensions/code-block'
import { shikiBundledLanguagesInfo } from 'prosekit/extensions/code-block'
import type { ReactNodeViewProps } from 'prosekit/react'

export default function CodeBlockView(props: ReactNodeViewProps) {
  const attrs = props.node.attrs as CodeBlockAttrs
  const language = attrs.language

  const setLanguage = (language: string) => {
    const attrs: CodeBlockAttrs = { language }
    props.setAttrs(attrs)
  }

  return (
    <>
      <div className="relative mx-2 top-3 h-0 select-none overflow-visible text-xs" contentEditable={false}>
        <select
          aria-label="Code block language"
          className="outline-unset focus:outline-unset relative box-border w-auto cursor-pointer select-none appearance-none rounded-sm border-none bg-transparent px-2 py-1 text-xs transition text-(--prosemirror-highlight) opacity-0 hover:opacity-80 [div[data-node-view-root]:hover_&]:opacity-50 hover:[div[data-node-view-root]:hover_&]:opacity-80"
          onChange={(event) => setLanguage(event.target.value)}
          value={language || ''}
        >
          <option value="">Plain Text</option>
          {shikiBundledLanguagesInfo.map((info) => (
            <option key={info.id} value={info.id}>
              {info.name}
            </option>
          ))}
        </select>
      </div>
      <pre ref={props.contentRef} data-language={language}></pre>
    </>
  )
}

import type { Extension } from 'prosekit/core'
import { defineReactNodeView, type ReactNodeViewComponent } from 'prosekit/react'

import CodeBlockView from './code-block-view'

export function defineCodeBlockView(): Extension {
  return defineReactNodeView({
    name: 'codeBlock',
    contentAs: 'code',
    component: CodeBlockView satisfies ReactNodeViewComponent,
  })
}

'use client'

import { DropIndicator as BaseDropIndicator } from 'prosekit/react/drop-indicator'

export default function DropIndicator() {
  return <BaseDropIndicator className="z-50 transition-all bg-blue-500" />
}

export { default as DropIndicator } from './drop-indicator'

Install

CLI
Manual

npx shadcn@latest add @prosekit/react-ui-block-handle

Structure

BlockHandleRoot                  # root component
└── BlockHandlePositioner        # anchors the popup to the gutter 
    └── BlockHandlePopup         # the floating container
        ├── BlockHandleAdd       # "+" button that inserts a new block below
        └── BlockHandleDraggable # "⋮⋮" drag handle that reorders by dragging

You can keep both BlockHandleAdd and BlockHandleDraggable, or only one. The popup is just the visible container. Pair this with the Drop indicator component to draw a horizontal line where the dragged block will land.

API reference

See also

Drop indicator: companion overlay that shows the drop target during a drag.
Table handle: sibling primitive for table-row and table-column selection.