Block Selection

'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>
  );
}

Kit Usage

'use client';
 
import { BlockSelectionPlugin } from '@platejs/selection/react';
import { getPluginTypes, KEYS } from 'platejs';
 
import { BlockSelection } from '@/components/ui/block-selection';
 
export const BlockSelectionKit = [
  BlockSelectionPlugin.configure(({ editor }) => ({
    options: {
      enableContextMenu: true,
      isSelectable: (element) => {
        return !getPluginTypes(editor, [
          KEYS.column,
          KEYS.codeLine,
          KEYS.table,
          KEYS.td,
        ]).includes(element.type);
      },
    },
    render: {
      belowRootNodes: (props) => {
        if (!props.attributes.className?.includes('slate-selectable'))
          return null;
 
        return <BlockSelection {...(props as any)} />;
      },
    },
  })),
];Copy

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

Manual Usage

pnpm add @platejs/selection

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

import { BlockSelectionPlugin } from '@platejs/selection/react';
 
BlockSelectionPlugin.configure({
  options: {
    isSelectable: (element, path) => {
      if (['code_line', 'column', 'td'].includes(element.type)) {
        return false;
      }
      // Exclude blocks inside table rows
      if (editor.api.block({ above: true, at: path, match: { type: 'tr' } })) {
        return false;
      }
      return true;
    },
  },
});Copy

BlockSelectionPlugin.configure({
  options: {
    areaOptions: {
      boundaries: `#${editor.meta.uid}`,
      container: `#${editor.meta.uid}`,
      behaviour: {
        scrolling: {
          // Recommended speed, close to native
          speedDivider: 0.8,
        },
        // Threshold to start selection area
        startThreshold: 4,
      },
    },
  },
});Copy

<Cover data-plate-selectable />
<Sidebar data-plate-selectable />Copy

<YourToolbarButton data-plate-prevent-unselect />Copy

// 1. Direct API call
editor.api.blockSelection.deselect();
 
// 2. Click outside handler
const handleClickOutside = (event: MouseEvent) => {
  if (!(event.target as HTMLElement).closest('[data-plate-selectable]')) {
    editor.api.blockSelection.deselect();
  }
};Copy

Styling

Selection Area

Style the selection area by targeting the .slate-selection-area class, which is added to the editor container.

/* Example using Tailwind CSS utility classes */
'[&_.slate-selection-area]:border [&_.slate-selection-area]:border-primary [&_.slate-selection-area]:bg-primary/10'Copy

Selected Element

Use the useBlockSelected hook to determine if a block is selected. You can render a visual indicator, like the BlockSelection component, which is designed for this purpose.

Plate UI renders this component for all selectable blocks using render.belowRootNodes:

render: {
  belowRootNodes: (props) => {
    if (!props.className?.includes('slate-selectable')) return null;
 
    return <BlockSelection />;
  },
},Copy

Plugins

BlockSelectionPlugin

Plugin for block selection functionality.

API

api.blockSelection.add

Adds one or more blocks to the selection.

api.blockSelection.clear

Resets the set of selected IDs to an empty set.

api.blockSelection.delete

Removes one or more blocks from the selection.

api.blockSelection.deselect

Deselects all blocks and sets the isSelecting flag to false.

api.blockSelection.focus

Focuses the block selection shadow input. This input handles copy, delete, and paste events for selected blocks.

api.blockSelection.getNodes

Gets the selected blocks in the editor.

api.blockSelection.has

Checks if one or more blocks are selected.

api.blockSelection.isSelectable

Checks if a block at a given path is selectable based on the isSelectable plugin option.

api.blockSelection.moveSelection

Moves the selection up or down to the next selectable block.

When moving up:

• Gets the previous selectable block from the top-most selected block
• Sets it as the new anchor
• Clears previous selection and selects only this block When moving down:
• Gets the next selectable block from the bottom-most selected block
• Sets it as the new anchor
• Clears previous selection and selects only this block

api.blockSelection.selectAll

Selects all selectable blocks in the editor.

api.blockSelection.set

Sets the selection to one or more blocks, clearing any existing selection.

api.blockSelection.shiftSelection

Expands or shrinks the selection based on the anchor block.

For Shift+ArrowDown:

• If anchor is top-most: Expands down by adding block below bottom-most
• Otherwise: Shrinks from top-most (unless top-most is the anchor) For Shift+ArrowUp:
• If anchor is bottom-most: Expands up by adding block above top-most
• Otherwise: Shrinks from bottom-most (unless bottom-most is the anchor) The anchor block always remains selected. If no anchor is set, it defaults to:
• Bottom-most block for Shift+ArrowUp
• Top-most block for Shift+ArrowDown

Transforms

tf.blockSelection.duplicate

Duplicates the selected blocks.

tf.blockSelection.removeNodes

Removes the selected nodes from the editor.

tf.blockSelection.select

Selects the nodes returned by getNodes() in the editor and resets selected IDs.

tf.blockSelection.setNodes

Sets properties on the selected nodes.

tf.blockSelection.setTexts

Sets text properties on the selected nodes.

Hooks

useBlockSelectable

A hook that provides props for making a block element selectable, including context menu behavior.

useBlockSelected

useBlockSelectionNodes

useBlockSelectionFragment

useBlockSelectionFragmentProp

useSelectionArea

Initialize and manage selection area functionality.