feature: Grouped custom rich editor blocks (#19653)

* feature: Grouped custom rich editor blocks

* screenshot

* Update RichContentAttribute.php

Author: danharrin

docs-assets/app/app/Livewire/Forms/Fields/RichEditorSchema.php

@@ -2,9 +2,13 @@
 
 namespace App\Livewire\Forms\Fields;
 
+use App\RichContentBlocks\AlertBlock;
+use App\RichContentBlocks\BannerBlock;
 use App\RichContentBlocks\CallToActionBlock;
 use App\RichContentBlocks\HeroBlock;
+use App\RichContentBlocks\ImageGalleryBlock;
 use App\RichContentBlocks\TestimonialBlock;
+use App\RichContentBlocks\VideoEmbedBlock;
 use Filament\Forms\Components\RichEditor;
 use Filament\Forms\Components\RichEditor\MentionProvider;
 use Filament\Forms\Components\RichEditor\TextColor;
@@ -122,6 +126,28 @@ public static function schema(): array
                             TestimonialBlock::class,
                         ]),
                 ]),
+            Group::make()
+                ->id('richEditorGroupedCustomBlocks')
+                ->extraAttributes([
+                    'class' => 'p-16 max-w-5xl',
+                ])
+                ->schema([
+                    RichEditor::make('richEditorGroupedCustomBlocks')
+                        ->label('Content')
+                        ->customBlocks([
+                            AlertBlock::class,
+                            'Marketing' => [
+                                HeroBlock::class,
+                                CallToActionBlock::class,
+                                BannerBlock::class,
+                                TestimonialBlock::class,
+                            ],
+                            'Media' => [
+                                ImageGalleryBlock::class,
+                                VideoEmbedBlock::class,
+                            ],
+                        ]),
+                ]),
             Group::make()
                 ->id('richEditorFloatingToolbar')
                 ->extraAttributes([

docs-assets/app/app/RichContentBlocks/AlertBlock.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace App\RichContentBlocks;
+
+use Filament\Forms\Components\RichEditor\RichContentCustomBlock;
+
+class AlertBlock extends RichContentCustomBlock
+{
+    public static function getId(): string
+    {
+        return 'alert';
+    }
+
+    public static function getLabel(): string
+    {
+        return 'Alert';
+    }
+}

docs-assets/app/app/RichContentBlocks/BannerBlock.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace App\RichContentBlocks;
+
+use Filament\Forms\Components\RichEditor\RichContentCustomBlock;
+
+class BannerBlock extends RichContentCustomBlock
+{
+    public static function getId(): string
+    {
+        return 'banner';
+    }
+
+    public static function getLabel(): string
+    {
+        return 'Banner';
+    }
+}

docs-assets/app/app/RichContentBlocks/ImageGalleryBlock.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace App\RichContentBlocks;
+
+use Filament\Forms\Components\RichEditor\RichContentCustomBlock;
+
+class ImageGalleryBlock extends RichContentCustomBlock
+{
+    public static function getId(): string
+    {
+        return 'image-gallery';
+    }
+
+    public static function getLabel(): string
+    {
+        return 'Image gallery';
+    }
+}

docs-assets/app/app/RichContentBlocks/VideoEmbedBlock.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace App\RichContentBlocks;
+
+use Filament\Forms\Components\RichEditor\RichContentCustomBlock;
+
+class VideoEmbedBlock extends RichContentCustomBlock
+{
+    public static function getId(): string
+    {
+        return 'video-embed';
+    }
+
+    public static function getLabel(): string
+    {
+        return 'Video embed';
+    }
+}

docs-assets/screenshots/images/dark/forms/fields/rich-editor/custom-blocks.jpg

@@ -1706,6 +1706,26 @@ export default {
             await new Promise((resolve) => setTimeout(resolve, 500))
         },
     },
+    'forms/fields/rich-editor/grouped-custom-blocks': {
+        url: 'forms/fields/rich-editor',
+        selector: '#richEditorGroupedCustomBlocks',
+        viewport: {
+            width: 1920,
+            height: 640,
+            deviceScaleFactor: 3,
+        },
+        before: async (page) => {
+            // Scroll into view so JS initializes.
+            await page.evaluate(() => {
+                document.querySelector('#richEditorGroupedCustomBlocks').scrollIntoView()
+            })
+            await new Promise((resolve) => setTimeout(resolve, 1000))
+
+            // Click the custom blocks toolbar button to open the side panel.
+            await page.click('#richEditorGroupedCustomBlocks button[aria-label="Blocks"]')
+            await new Promise((resolve) => setTimeout(resolve, 500))
+        },
+    },
     'forms/fields/rich-editor/floating-toolbar': {
         url: 'forms/fields/rich-editor',
         selector: '#richEditorFloatingToolbar',

docs-assets/screenshots/images/dark/forms/fields/rich-editor/grouped-custom-blocks.jpg

@@ -598,6 +598,50 @@ RichContentRenderer::make($record->content)
     ->toHtml()
 ```
 
+### Grouping custom blocks
+
+You can organize custom blocks into groups using string keys in the `customBlocks()` array. Blocks passed directly (without a string key) are ungrouped and appear first in the panel:
+
+```php
+use Filament\Forms\Components\RichEditor;
+
+RichEditor::make('content')
+    ->customBlocks([
+        AlertBlock::class,
+        DividerBlock::class,
+        'Marketing' => [
+            HeroBlock::class,
+            CallToActionBlock::class,
+            BannerBlock::class,
+        ],
+        'Media' => [
+            ImageGalleryBlock::class,
+            VideoEmbedBlock::class,
+        ],
+    ])
+```
+
+<AutoScreenshot name="forms/fields/rich-editor/grouped-custom-blocks" alt="Rich editor with grouped custom blocks panel open" version="4.x" />
+
+Groups are displayed in the order they are defined in the array, with sticky headings in the side panel.
+
+When rendering content with grouped blocks, you can pass the same grouped array structure to the `RichContentRenderer`. Groups are ignored during rendering — only the block classes are used:
+
+```php
+use Filament\Forms\Components\RichEditor\RichContentRenderer;
+
+RichContentRenderer::make($record->content)
+    ->customBlocks([
+        'Marketing' => [
+            HeroBlock::class => [
+                'categoryUrl' => $record->category->getUrl(),
+            ],
+            CallToActionBlock::class,
+        ],
+    ])
+    ->toHtml()
+```
+
 ### Opening the custom blocks panel by default
 
 If you want the custom blocks panel to be open by default when the rich editor is loaded, you can use the `activePanel('customBlocks')` method: