Docs
Block Selection

Block Selection

Select and manipulate entire text blocks.

📸 Image

Add images by either uploading them or providing the image URL:

Customize image captions and resize images.

📺 Embed

Embed various types of content, such as videos and tweets:



Features

  • Select entire blocks, as opposed to individual words or characters.
  • To select an entire block, mouse down outside the text area and then move the cursor into the block. Once it is selected, you'll see a background color.
  • Keep moving down or up to select multiple blocks.
  • Once selected, the available actions are: copy, cut, and delete.
  • Keyboard shortcuts:
    • Cmd+A (Mac) / Ctrl+A (Windows/Linux):
      • First press: Selects the current block
      • Double press: Selects the whole document using block selection
    • Note: This behavior can be disabled by setting handlers.onKeyDown = null when creating the plugin

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,
];

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.
  2. Use the appropriate selector in your configuration.

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}
    />

Styling

Selection area

You can style the selection area by adding this class to the container(.slate-selection-area can be changed in the plugin options):

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

Selected element

You can style the selected element by adding this class to the container

'[&]:!bg-primary/20'

Disable browser default scroll behavior

If we select some text and then move(keep pressed) the cursor to the very bottom of the page, the page will start scrolling to the bottom.

This scroll is so fast and confilicts with BlockSelectionPlugin scroll behavior(After the selection area appears, move the mouse to the bottom of the scroll container).

I don't find any way to disable this scroll behavior of browser.(if you find the way to disable it, please tell me that will so appreciate it)So the solution is add an empty div above the editer's right side(The right side is the easiest place to trigger this behavior.) and set user-select: none to it .

If you find this issue occurring in your editor, please check the width of this div. You can use the option editorPaddingRight to set the width of this div or the class rightSelectionAreaClassName to style it.

Make sure the width is the same with the editor's padding-right.

Plugins

BlockSelectionPlugin

Options

Collapse all

    Options for the selection area. Example:

    {
  boundaries: ['#selection-demo #scroll_container'],
  container: ['#selection-demo #scroll_container'],
  selectables: ['#selection-demo #scroll_container .slate-selectable'],
  selectionAreaClass: 'slate-selection-area',
}

    The padding-right of the editor.

    Enables or disables the context menu for block selection.

    • Default: false

    Indicates whether block selection is currently active.

    • Default: false

    A function to handle the keydown event when selecting.

    Options for querying nodes during block selection.

    • Default: { maxLevel: 1 }

    A set of IDs for the currently selected blocks.

    • Default: new Set()

BlockContextMenuPlugin

This plugin is used by BlockSelectionPlugin and doesn't need to be added manually.

API

editor.api.blockSelection.addSelectedRow

Adds a selected row to the block selection.

Parameters

Collapse all

    The ID of the row to be selected.

editor.api.blockSelection.getSelectedBlocks

Gets the selected blocks in the editor.

Returns

Collapse all

    An array of selected block entries.

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.

Parameters

Collapse all

editor.api.blockSelection.unselect

Unselects all blocks and sets the isSelecting flag to false.

API Components

BlockSelectable

Props

Collapse all

BlockSelection

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

Props

Collapse all

    The content to be wrapped with block selection functionality.

Hooks

useBlockSelectableState

Returns

Collapse all

    Whether the block is active for selection.

    The element associated with the block.

    The path of the block in the editor.

    A ref to the block's DOM element.

useBlockSelectable

Returns

Collapse all

    Props to be spread on the block's wrapper element.

useSelectionArea

A hook that initializes and manages the selection area functionality.

Basic MarksCaption