Block Selection

Installation

npm install @udecode/plate-selection @udecode/plate-node-id

Usage

import { NodeIdPlugin } from '@udecode/plate-node-id';
import { BlockSelectionPlugin } from '@udecode/plate-selection/react';
 
const plugins = [
  // ...otherPlugins,
  NodeIdPlugin,
  BlockSelectionPlugin,
];

Configuration

Set scrollable container

To control the scrollable container, configure the boundaries and container options within areaOptions. These options accept CSS selectors, such as #selection-demo #scroll_container, which are used with document.querySelector().

For this to work effectively:

1. Add an id or className to your scroll container.If you not sure about the container, you can add it to the <Editor /> component.
2. Use the appropriate selector in your configuration.
3. Don't forget to set position: relative to your scroll container.

Example configuration:

{
  areaOptions: {
    boundaries: '#your-scroll-container-id',
    container: '#your-scroll-container-id',
    selectables: '#your-scroll-container-id .slate-selectable',
    selectionAreaClass: 'slate-selection-area',
  }
}

This setup ensures that the block selection functionality is properly constrained within your designated scrollable area.

Set selectable element

Add data-plate-selectable to the container or the element you want to start block selection.

Example:

   <PlateContent
    aria-disabled={disabled}
    className={cn(
      editorVariants({
        disabled,
        focusRing,
        focused,
        size,
        variant,
      }),
      className
    )}
    data-plate-selectable
    disableDefaultStyles
    readOnly={disabled ?? readOnly}
    {...props}
    />

Set scroll speed

useing options.areaOptions.behaviour.scrolling.speedDivider to set the scroll speed.

The value of 1.5 is our recommended speed.Since it's same with the default speed of the browser.

  areaOptions: {
      behaviour: {
        scrolling: {
          speedDivider: 1.5,
        },
      },
  },

Full configuration recommended:

options: {
  areaOptions: {
    behaviour: {
      scrolling: {
        speedDivider: 1.5,
      },
      // The distance needed to move for the selection area to appear.
      // If it’s too small, it may cause the mouse click event to be blocked. 30 is a good default.
      startThreshold: 30,
    },
    boundaries: '#your-scroll-container-id',
    container: '#your-scroll-container-id',
    selectables: '#your-scroll-container-id .slate-selectable',
    selectionAreaClass: 'slate-selection-area',
  },
  // if not using plate-ui context menu, set it to false
  enableContextMenu: true,
},

Styling

Selection area

Style the selection area using .slate-selection-area class to your EditorContainer component. For example:

'[&_.slate-selection-area]:border [&_.slate-selection-area]:border-primary [&_.slate-selection-area]:bg-primary/10'

Selected element

To determine if an element is selected, use the new useBlockSelected hook. You can render a visual indicator around selected blocks using our BlockSelection component or create your own:

import React from 'react';
import { useBlockSelected } from '@udecode/plate-selection/react';
 
export function BlockSelection() {
  const isBlockSelected = useBlockSelected();
 
  return (
    <div
      className={`pointer-events-none absolute inset-0 z-10 bg-primary/15 ${
        isBlockSelected ? 'opacity-100' : 'opacity-0'
      }`}
    />
  );
}

This component should be rendered inside each block element for consistent selection feedback. Plate UI is doing it in plate-element.tsx.

Selectable and resetable

full page selectable

Like the potion template, you can enable block selection outside of the <Editor /> component.

Simply add the data-plate-selectable attribute to any component outside the editor that you want to make selectable. You can even make the entire page selectable if desired.

For example:

<Cover data-plate-selectable />

full page resetable

To reset the selection, you need call the api.blockSelection.unselect(); method.

If you want to make the full page resetable by click, this means you need to be able to access the editor outside of <Editor />.

Or you can implement a click outside handler to reset the selection.

Prevent unselect

To prevent unselecting blocks when clicking on certain elements, add the data-plate-prevent-unselect attribute to those components

For example:

  <YourSpecialButtoon data-plate-prevent-unselect />

Plugins

BlockSelectionPlugin

BlockMenuPlugin

API

editor.api.blockSelection.focus

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

editor.api.blockSelection.addSelectedRow

Adds a selected row to the block selection.

editor.api.blockSelection.getNodes

Gets the selected blocks in the editor.

editor.api.blockSelection.resetSelectedIds

Resets the set of selected IDs to an empty set.

editor.api.blockSelection.selectedAll

Selects all selectable blocks in the editor.

editor.api.blockSelection.setSelectedIds

Sets the selected IDs based on added and removed elements.

editor.api.blockSelection.unselect

Unselects all blocks and sets the isSelecting flag to false.

Transforms

editor.tf.blockSelection.duplicate

Duplicates the selected blocks.

editor.tf.blockSelection.removeNodes

Removes the selected nodes from the editor.

editor.tf.blockSelection.select

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

editor.tf.blockSelection.setNodes

Sets properties on the selected nodes.

editor.tf.blockSelection.setTexts

Sets text properties on the selected nodes.

API Components

BlockSelectable

BlockSelection

A wrapper component that adds block selection functionality to its children.

Hooks

useBlockSelected

Returns true if context block is selected.

useBlockSelectableState

useBlockSelectable

useSelectionArea

A hook that initializes and manages the selection area functionality.

useBlockSelectionNodes

Returns an array of node entries for the currently selected blocks.

useBlockSelectionFragment

Returns an array of nodes for the currently selected blocks.

useBlockSelectionFragmentProp

Returns fragment prop for the currently selected blocks.