From fdab2712c06280c3a2d6ea78606d4ad58c313b7b Mon Sep 17 00:00:00 2001
From: Riley Langbein <54197972+rilrom@users.noreply.github.com>
Date: Sun, 31 Aug 2025 15:21:00 +0930
Subject: [PATCH] feat(richtext-lexical): add options to hide block handles
 (#13647)

### What?

Currently the `DraggableBlockPlugin` and `AddBlockHandlePlugin`
components are automatically applied to every editor. For flexibility
purposes, we want to allow these to be optionally removed when needed.

### Why?

There are scenarios where you may want to enforce certain limitations on
an editor, such as only allowing a single line of text. The draggable
block element and add block button wouldn't play nicely with this
scenario.

Previously in order to do this, you needed to use custom css to hide the
elements, which still technically allows them to be accessible to the
end-user if they removed the CSS. This implementation ensures the
handlers are properly removed when not wanted.

### How?

Add `hideDraggableBlockElement` and `hideAddBlockButton` options to the
lexical `admin` property. When these are set to `true`, the
`DraggableBlockPlugin` and `AddBlockHandlePlugin` are not rendered to
the DOM.

Addresses #13636
---
 docs/rich-text/overview.mdx                          | 12 +++++++-----
 packages/richtext-lexical/src/field/rscEntry.tsx     |  6 ++++++
 .../richtext-lexical/src/lexical/LexicalEditor.tsx   |  8 ++++++--
 packages/richtext-lexical/src/types.ts               |  8 ++++++++
 4 files changed, 27 insertions(+), 7 deletions(-)

diff --git a/docs/rich-text/overview.mdx b/docs/rich-text/overview.mdx
index cd6a55d8a7..680f1f245a 100644
--- a/docs/rich-text/overview.mdx
+++ b/docs/rich-text/overview.mdx
@@ -269,11 +269,13 @@ Lexical does not generate accurate type definitions for your richText fields for
 
 The Rich Text Field editor configuration has an `admin` property with the following options:
 
-| Property                       | Description                                                                              |
-| ------------------------------ | ---------------------------------------------------------------------------------------- |
-| **`placeholder`**              | Set this property to define a placeholder string for the field.                          |
-| **`hideGutter`**               | Set this property to `true` to hide this field's gutter within the Admin Panel.          |
-| **`hideInsertParagraphAtEnd`** | Set this property to `true` to hide the "+" button that appears at the end of the editor |
+| Property                        | Description                                                                                                 |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| **`placeholder`**               | Set this property to define a placeholder string for the field.                                             |
+| **`hideGutter`**                | Set this property to `true` to hide this field's gutter within the Admin Panel.                             |
+| **`hideInsertParagraphAtEnd`**  | Set this property to `true` to hide the "+" button that appears at the end of the editor.                   |
+| **`hideDraggableBlockElement`** | Set this property to `true` to hide the draggable element that appears when you hover a node in the editor. |
+| **`hideAddBlockButton`**        | Set this property to `true` to hide the "+" button that appears when you hover a node in the editor.        |
 
 ### Disable the gutter
 
diff --git a/packages/richtext-lexical/src/field/rscEntry.tsx b/packages/richtext-lexical/src/field/rscEntry.tsx
index 6c3f663e2f..b231a8a706 100644
--- a/packages/richtext-lexical/src/field/rscEntry.tsx
+++ b/packages/richtext-lexical/src/field/rscEntry.tsx
@@ -85,6 +85,12 @@ export const RscEntryLexicalField: React.FC<
   if (args.admin?.hideInsertParagraphAtEnd) {
     admin.hideInsertParagraphAtEnd = true
   }
+  if (args.admin?.hideAddBlockButton) {
+    admin.hideAddBlockButton = true
+  }
+  if (args.admin?.hideDraggableBlockElement) {
+    admin.hideDraggableBlockElement = true
+  }
 
   const props: LexicalRichTextFieldProps = {
     clientFeatures,
diff --git a/packages/richtext-lexical/src/lexical/LexicalEditor.tsx b/packages/richtext-lexical/src/lexical/LexicalEditor.tsx
index d7a2ddf182..44a02bbbf3 100644
--- a/packages/richtext-lexical/src/lexical/LexicalEditor.tsx
+++ b/packages/richtext-lexical/src/lexical/LexicalEditor.tsx
@@ -131,8 +131,12 @@ export const LexicalEditor: React.FC<
           <React.Fragment>
             {!isSmallWidthViewport && editor.isEditable() && (
               <React.Fragment>
-                <DraggableBlockPlugin anchorElem={floatingAnchorElem} />
-                <AddBlockHandlePlugin anchorElem={floatingAnchorElem} />
+                {editorConfig.admin?.hideDraggableBlockElement ? null : (
+                  <DraggableBlockPlugin anchorElem={floatingAnchorElem} />
+                )}
+                {editorConfig.admin?.hideAddBlockButton ? null : (
+                  <AddBlockHandlePlugin anchorElem={floatingAnchorElem} />
+                )}
               </React.Fragment>
             )}
             {editorConfig.features.plugins?.map((plugin) => {
diff --git a/packages/richtext-lexical/src/types.ts b/packages/richtext-lexical/src/types.ts
index fb36c429db..1f8e87006b 100644
--- a/packages/richtext-lexical/src/types.ts
+++ b/packages/richtext-lexical/src/types.ts
@@ -20,6 +20,14 @@ import type { SanitizedServerEditorConfig } from './lexical/config/types.js'
 import type { InitialLexicalFormState } from './utilities/buildInitialState.js'
 
 export type LexicalFieldAdminProps = {
+  /**
+   * Controls if the add block button should be hidden. @default false
+   */
+  hideAddBlockButton?: boolean
+  /**
+   * Controls if the draggable block element should be hidden. @default false
+   */
+  hideDraggableBlockElement?: boolean
   /**
    * Controls if the gutter (padding to the left & gray vertical line) should be hidden. @default false
    */