Rich editor - Filament

Introduction

The rich editor allows you to edit and preview HTML content, as well as upload images. It uses TipTap as the underlying editor.

use Filament\Forms\Components\RichEditor;

RichEditor::make('content')

Storing content as JSON

By default, the rich editor stores content as HTML. If you would like to store the content as JSON instead, you can use the json() method:

use Filament\Forms\Components\RichEditor;

RichEditor::make('content')
    ->json()

The JSON is in TipTap’s format, which is a structured representation of the content. If you’re saving the JSON content using Eloquent, you should be sure to add an array cast to the model property:

use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    /**
     * @return array<string, string>
     */
    protected function casts(): array
    {
        return [
            'content' => 'array',
        ];
    }

    // ...
}

You may set the toolbar buttons for the editor using the toolbarButtons() method. The options shown here are the defaults:

use Filament\Forms\Components\RichEditor;

RichEditor::make('content')
    ->toolbarButtons([
        ['bold', 'italic', 'underline', 'strike', 'subscript', 'superscript', 'link'],
        ['h2', 'h3'],
        ['alignStart', 'alignCenter', 'alignEnd'],
        ['blockquote', 'codeBlock', 'bulletList', 'orderedList'],
        ['table', 'attachFiles'], // The `customBlocks` and `mergeTags` tools are also added here if those features are used.
        ['undo', 'redo'],
    ])

Each nested array in the main array represents a group of buttons in the toolbar. Additional tools available in the toolbar include:

h1 - Applies the “h1” tag to the text.
h4 - Applies the “h4” tag to the text.
h5 - Applies the “h5” tag to the text.
h6 - Applies the “h6” tag to the text.
alignJustify - Justifies the text.
clearFormatting - Clears all formatting from the selected text.
details - Inserts a <details> tag, which allows users to create collapsible sections in their content.
grid - Inserts a grid layout into the editor, allowing users to create responsive columns of content.
gridDelete - Deletes the current grid layout.
highlight - Highlights the selected text with a <mark> tag around it.
horizontalRule - Inserts a horizontal rule.
lead - Applies a lead class around the text, which is typically used for the first paragraph of an article.
paragraph - Sets the current block to a paragraph, removing any heading formatting.
small - Applies the <small> tag to the text, which is typically used for small print or disclaimers.
code - Format the selected text as inline code.
textColor - Changes the text color of the selected text.
table - Creates a table in the editor with a default layout of 3 columns and 2 rows, with the first row configured as a header row.
tableAddColumnBefore - Adds a new column before the current column.
tableAddColumnAfter - Adds a new column after the current column.
tableDeleteColumn - Deletes the current column.
tableAddRowBefore - Adds a new row above the current row.
tableAddRowAfter - Adds a new row below the current row.
tableDeleteRow - Deletes the current row.
tableMergeCells - Merges the selected cells into one cell.
tableSplitCell - Splits the selected cell into multiple cells.
tableToggleHeaderRow - Toggles the header row of the table.
tableToggleHeaderCell - Toggles the header cell of the table.
tableDelete - Deletes the table.

Customizing floating toolbars

If your toolbar is too full, you can use a floating toolbar to show certain tools in a toolbar below the cursor, only when the user is inside a specific node type. This allows you to keep the main toolbar clean while still providing access to additional tools when needed. You can customize the floating toolbars that appear when your cursor is placed inside a specific node by using the floatingToolbars() method. In the example below, a floating toolbar appears when the cursor is inside a paragraph node. It shows bold, italic, and similar buttons. When the cursor is in a heading node, it displays heading-related buttons, and when inside a table, it shows table-specific controls.

use Filament\Forms\Components\RichEditor;

RichEditor::make('content')
    ->floatingToolbars([
        'paragraph' => [
            'bold', 'italic', 'underline', 'strike', 'subscript', 'superscript',
        ],
        'heading' => [
            'h1', 'h2', 'h3',
        ],
        'table' => [
            'tableAddColumnBefore', 'tableAddColumnAfter', 'tableDeleteColumn',
            'tableAddRowBefore', 'tableAddRowAfter', 'tableDeleteRow',
            'tableMergeCells', 'tableSplitCell',
            'tableToggleHeaderRow', 'tableToggleHeaderCell',
            'tableDelete',
        ],
    ])

You may group related toolbar buttons into a dropdown menu using ToolbarButtonGroup. The first argument is a label used for the dropdown’s tooltip and accessibility, and the second argument is an array of button names to include in the dropdown:

use Filament\Forms\Components\RichEditor;
use Filament\Forms\Components\RichEditor\ToolbarButtonGroup;

RichEditor::make('content')
    ->toolbarButtons([
        ['bold', 'italic', 'underline', 'strike'],
        [ToolbarButtonGroup::make('Paragraph', ['paragraph', 'h1', 'h2', 'h3'])],
        [ToolbarButtonGroup::make('Alignment', ['alignStart', 'alignCenter', 'alignEnd', 'alignJustify'])],
        ['blockquote', 'codeBlock', 'bulletList', 'orderedList'],
        ['undo', 'redo'],
    ])

By default, the first button’s icon is used as the dropdown trigger, and it updates reactively to reflect the currently active button. Clicking on the trigger reveals the grouped buttons. You can set a fixed icon for the dropdown trigger using the icon() method. When a custom icon is set, the trigger icon remains static and does not change based on the active button:

use Filament\Forms\Components\RichEditor;
use Filament\Forms\Components\RichEditor\ToolbarButtonGroup;

RichEditor::make('content')
    ->toolbarButtons([
        ['bold', 'italic', 'underline', 'strike'],
        [ToolbarButtonGroup::make('Heading', ['h1', 'h2', 'h3'])->icon('fi-o-heading')],
        [ToolbarButtonGroup::make('Alignment', ['alignStart', 'alignCenter', 'alignEnd', 'alignJustify'])],
        ['blockquote', 'codeBlock', 'bulletList', 'orderedList'],
        ['undo', 'redo'],
    ])

By default, dropdown toolbar buttons display icons only. If you’d like to show text labels alongside icons in the dropdown items, you can use the textualButtons() method on a ToolbarButtonGroup:

use Filament\Forms\Components\RichEditor;
use Filament\Forms\Components\RichEditor\ToolbarButtonGroup;

RichEditor::make('content')
    ->toolbarButtons([
        ['bold', 'italic', 'underline', 'strike', 'link'],
        [ToolbarButtonGroup::make('Paragraph', ['paragraph', 'h1', 'h2', 'h3'])->textualButtons()],
        [ToolbarButtonGroup::make('Alignment', ['alignStart', 'alignCenter', 'alignEnd', 'alignJustify'])],
        ['blockquote', 'codeBlock', 'bulletList', 'orderedList'],
        ['undo', 'redo'],
    ])

In this example, the Paragraph dropdown items display their icon alongside a text label (e.g., “Paragraph”, “Heading 1”). The Alignment dropdown remains icon-only.

Customizing text colors

The rich editor includes a text color tool for styling inline text. By default, it uses the Tailwind CSS color palette. In light mode, the 600 shades are applied to text, and in dark mode, the 400 shades are used. You can customize which colors are available in the picker using the textColors() method:

use Filament\Forms\Components\RichEditor;

RichEditor::make('content')
    ->textColors([
        '#ef4444' => 'Red',
        '#10b981' => 'Green',
        '#0ea5e9' => 'Sky',
    ])

If you would like to define different colors for light and dark mode, you can use the a TextColor object to define the color:

use Filament\Forms\Components\RichEditor;
use Filament\Forms\Components\RichEditor\TextColor;

RichEditor::make('content')
    ->textColors([
        'brand' => TextColor::make('Brand', '#0ea5e9'),
        'warning' => TextColor::make('Warning', '#f59e0b', darkColor: '#fbbf24'),
    ])

If you would like to add new colors onto the existing Tailwind palette, you can merge your colors into the TextColor::getDefaults() array:

use Filament\Forms\Components\RichEditor;
use Filament\Forms\Components\RichEditor\TextColor;

RichEditor::make('content')
    ->textColors([
        'brand' => TextColor::make('Brand', '#0ea5e9'),
        'warning' => TextColor::make('Warning', '#f59e0b', darkColor: '#fbbf24'),
        ...TextColor::getDefaults(),
    ])

When you use a TextColor object, the key of the array becomes the stored data-color attribute on the <span> tag, allowing you to reference the color in your CSS if needed. When you use the color as the array values, the actual color value (e.g., a HEX string) is stored as the data-color attribute. You can also pass textColors() to the content renderer and rich content attribute so that server-side rendering matches your editor configuration. You can also allow users to pick custom colors that aren’t in the predefined list by using the customTextColors() method:

use Filament\Forms\Components\RichEditor;

RichEditor::make('content')
    ->textColors([
        // ...
    ])
    ->customTextColors()

You do not need to use customTextColors() on the content renderer, as it will automatically render any custom colors that are used in the content.

Rendering rich content

If you’re storing content as JSON instead of HTML, or your content requires processing to inject private image URLs or similar, you’ll need to use the RichContentRenderer tool in Filament to output HTML:

use Filament\Forms\Components\RichEditor\RichContentRenderer;

RichContentRenderer::make($record->content)->toHtml()

The toHtml() method returns a string. If you would like to output HTML in a Blade view without escaping the HTML, you can echo the RichContentRender object without calling toHtml():

{{ \Filament\Forms\Components\RichEditor\RichContentRenderer::make($record->content) }}

If you have configured the file attachments behavior of the editor to change the disk or visibility of the uploaded files, you must also pass these settings to the renderer to ensure that the correct URLs are generated:

use Filament\Forms\Components\RichEditor\RichContentRenderer;

RichContentRenderer::make($record->content)
    ->fileAttachmentsDisk('s3')
    ->fileAttachmentsVisibility('private')
    ->toHtml()

If you are using custom blocks in the rich editor, you can pass an array of custom blocks to the renderer to ensure that they are rendered correctly:

use Filament\Forms\Components\RichEditor\RichContentRenderer;

RichContentRenderer::make($record->content)
    ->customBlocks([
        HeroBlock::class => [
            'categoryUrl' => $record->category->getUrl(),
        ],
        CallToActionBlock::class,
    ])
    ->toHtml()

If you are using merge tags, you can pass an array of values to replace the merge tags with:

use Filament\Forms\Components\RichEditor\RichContentRenderer;

RichContentRenderer::make($record->content)
    ->mergeTags([
        'name' => $record->user->name,
        'today' => now()->toFormattedDateString(),
    ])
    ->toHtml()

If you are using custom text colors, you can pass an array of colors to the renderer to ensure that the colors are rendered correctly:

use Filament\Forms\Components\RichEditor\RichContentRenderer;
use Filament\Forms\Components\RichEditor\TextColor;

RichContentRenderer::make($record->content)
    ->textColors([
        'brand' => TextColor::make('Brand', '#0ea5e9', darkColor: '#38bdf8'),
    ])
    ->toHtml();

Styling the rendered content

The rich editor HTML uses a combination of HTML elements, CSS classes, and inline styles to style the content, depending on the features used in the editor. If you render the content in a Filament table column or infolist entry with prose(), Filament will automatically apply the necessary styles for you. If you are outputting the content in your own Blade view, you may need to add some additional styles to ensure that the content is styled correctly. One way of styling the content is to use Tailwind CSS Typography. This plugin provides a set of pre-defined styles for common HTML elements, such as headings, paragraphs, lists, and tables. You can apply these styles to a container element using the prose class:

<div class="prose dark:prose-invert">
    {!! \Filament\Forms\Components\RichEditor\RichContentRenderer::make($record->content) !!}
</div>

However, some features, such as the grid layout and text colors, require additional styles that are not included in the Tailwind CSS Typography plugin. Filament also includes its own fi-prose CSS class that adds these additional styles. Any app that loads Filament’s vendor/filament/support/resources/css/index.css CSS will have access to this class. The styling is different to the prose class, but fits with Filament’s design system better:

<div class="fi-prose">
    {!! \Filament\Forms\Components\RichEditor\RichContentRenderer::make($record->content) !!}
</div>

Security

By default, the editor outputs raw HTML, and sends it to the backend. Attackers are able to intercept the value of the component and send a different raw HTML string to the backend. As such, it is important that when outputting the HTML from a rich editor, it is sanitized; otherwise your site may be exposed to Cross-Site Scripting (XSS) vulnerabilities. When Filament outputs raw HTML from the database in components such as TextColumn and TextEntry, it sanitizes it to remove any dangerous JavaScript. However, if you are outputting the HTML from a rich editor in your own Blade view, this is your responsibility. One option is to use Filament’s sanitizeHtml() helper to do this, which is the same tool we use to sanitize HTML in the components mentioned above:

{!! str($record->content)->sanitizeHtml() !!}

If you’re storing content as JSON instead of HTML, or your content requires processing to inject private image URLs or similar, you can use the content renderer to output HTML. This will automatically sanitize the HTML for you, so you don’t need to worry about it.

Filament’s built-in HTML sanitizer permits inline style attributes in order to support rich text formatting features such as font colors, text highlighting, and image sizing. This means that CSS properties like background: url(...) or position: fixed will not be stripped from sanitized HTML. If your content comes from untrusted users, you should consider restricting the default configuration. See the security documentation for details on how to customize the sanitizer.

Uploading images to the editor

By default, uploaded images are stored publicly on your storage disk, so that the rich content stored in the database can be output easily anywhere. You may customize how images are uploaded using configuration methods:

use Filament\Forms\Components\RichEditor;

RichEditor::make('content')
    ->fileAttachmentsDisk('s3')
    ->fileAttachmentsDirectory('attachments')
    ->fileAttachmentsVisibility('private')

Filament also supports spatie/laravel-medialibrary for storing rich editor file attachments. See our plugin documentation for more information.

Using private images in the editor

Using private images in the editor adds a layer of complexity to the process, since private images cannot be accessed directly via a permanent URL. Each time the editor is loaded or its content is rendered, temporary URLs need to be generated for each image, which are never stored in the database. Instead, Filament adds a data-id attribute to the image tags, which contains an identifier for the image in the storage disk, so that a temporary URL can be generated on demand. When rendering the content using private images, ensure that you are using the RichContentRenderer tool in Filament to output HTML:

use Filament\Forms\Components\RichEditor\RichContentRenderer;

RichContentRenderer::make($record->content)
    ->fileAttachmentsDisk('s3')
    ->fileAttachmentsVisibility('private')
    ->toHtml()

Securing file attachment IDs

The data-id attribute on an image node is an identifier for a file on the configured disk. When the content is rendered, Filament generates a URL for it — a signed temporary URL if the visibility is private. Like any other Livewire form field value, the content and its data-id attributes are controlled by the client: a request can be intercepted to change a data-id to any other identifier on the same disk. If the disk also stores files belonging to other users or records, an attacker could otherwise cause the rendered content to reference (and serve a signed URL for) someone else’s file. Filament allows this by default because legitimate features depend on it — for example, an action that inserts an image from a pre-existing library, or a “copy from another record” button. If none of your editors rely on such a flow, call preventFileAttachmentPathTampering() on the field to enable a built-in check:

use Filament\Forms\Components\RichEditor;

RichEditor::make('content')
    ->preventFileAttachmentPathTampering()

Filament parses the record’s original content (via $record->getOriginal() for the attribute matching the field name) and allows only the data-id values already present. Any other existing data-id causes the field to fail validation, so the record is never saved with a tampered value. Newly uploaded images always pass through. The default file attachment provider performs no per-record scoping — any data-id that resolves to a file on the configured disk is accepted unless you enable preventFileAttachmentPathTampering() (or isolate uploads at the disk/directory level). If instead you are using the spatie/laravel-medialibrary plugin as the file attachment provider, this protection is already implicit — it looks up each data-id against the record’s own media collection via $media->has($file), so a data-id for another record’s media is rejected automatically.

preventFileAttachmentPathTampering() needs a record on the form. Without one — for example, on a create page — every existing data-id fails validation unless the allowFilePathUsing callback approves it. New uploads are unaffected.

To apply this check to every RichEditor in your application without repeating it on each field, call configureUsing() in a service provider’s boot() method:

use Filament\Forms\Components\RichEditor;

RichEditor::configureUsing(function (RichEditor $component): void {
    $component->preventFileAttachmentPathTampering();
});

Individual fields can still opt out by calling preventFileAttachmentPathTampering(false).

Allowing additional `data-id` values with a callback

If your application legitimately references an identifier that is not on the record — for example, a “copy from another record” action — pass the allowFilePathUsing argument to approve it. Approved identifiers bypass the validation error:

use Filament\Forms\Components\RichEditor;

RichEditor::make('content')
    ->preventFileAttachmentPathTampering(
        allowFilePathUsing: fn (string $file): bool => str_starts_with($file, 'templates/'),
    )

The validation error message can be customized via validationMessages() using the tampered key:

use Filament\Forms\Components\RichEditor;

RichEditor::make('content')
    ->preventFileAttachmentPathTampering()
    ->validationMessages([
        'tampered' => 'The content references an image that is not permitted.',
    ])

Validating uploaded images

You may use the fileAttachmentsAcceptedFileTypes() method to control a list of accepted mime types for uploaded images. By default, image/png, image/jpeg, image/gif, and image/webp are accepted:

use Filament\Forms\Components\RichEditor;

RichEditor::make('content')
    ->fileAttachmentsAcceptedFileTypes(['image/png', 'image/jpeg'])

You may use the fileAttachmentsMaxSize() method to control the maximum file size for uploaded images. The size is specified in kilobytes. By default, the maximum size is 12288 KB (12 MB):

use Filament\Forms\Components\RichEditor;

RichEditor::make('content')
    ->fileAttachmentsMaxSize(5120) // 5 MB

Allowing users to resize images

By default, images in the editor cannot be resized by the user. You may enable image resizing using the resizableImages() method:

use Filament\Forms\Components\RichEditor;

RichEditor::make('content')
    ->resizableImages()

When enabled, users can resize images by clicking on them and dragging the resize handles. The aspect ratio is always preserved when resizing.

Using custom blocks

Custom blocks are elements that users can drag and drop into the rich editor. You can define custom blocks that user can insert into the rich editor using the customBlocks() method:

use Filament\Forms\Components\RichEditor;

RichEditor::make('content')
    ->customBlocks([
        HeroBlock::class,
        CallToActionBlock::class,
    ])

To create a custom block, you can use the following command:

php artisan make:filament-rich-content-custom-block HeroBlock

Each block needs a corresponding class that extends the Filament\Forms\Components\RichEditor\RichContentCustomBlock class. The getId() method should return a unique identifier for the block, and the getLabel() method should return the label that will be displayed in the editor’s side panel:

use Filament\Forms\Components\RichEditor\RichContentCustomBlock;

class HeroBlock extends RichContentCustomBlock
{
    public static function getId(): string
    {
        return 'hero';
    }

    public static function getLabel(): string
    {
        return 'Hero section';
    }
}

When a user drags a custom block into the editor, you can choose to open a modal to collect additional information from the user before inserting the block. To do this, you can use the configureEditorAction() method to configure the modal that will be opened when the block is inserted:

use Filament\Actions\Action;
use Filament\Forms\Components\RichEditor\RichContentCustomBlock;

class HeroBlock extends RichContentCustomBlock
{
    // ...

    public static function configureEditorAction(Action $action): Action
    {
        return $action
            ->modalDescription('Configure the hero section')
            ->schema([
                TextInput::make('heading')
                    ->required(),
                TextInput::make('subheading'),
            ]);
    }
}

The schema() method on the action can define form fields that will be displayed in the modal. When the user submits the form, the form data will be saved as “configuration” for that block.

Rendering a preview for a custom block

Once a block is inserted into the editor, you may define a “preview” for it using the toPreviewHtml() method. This method should return a string of HTML that will be displayed in the editor when the block is inserted, allowing users to see what the block will look like before they save it. You can access the $config for the block in this method, which contains the data that was submitted in the modal when the block was inserted:

use Filament\Forms\Components\RichEditor\RichContentCustomBlock;

class HeroBlock extends RichContentCustomBlock
{
    // ...

    /**
     * @param  array<string, mixed>  $config
     */
    public static function toPreviewHtml(array $config): string
    {
        return view('filament.forms.components.rich-editor.rich-content-custom-blocks.hero.preview', [
            'heading' => $config['heading'],
            'subheading' => $config['subheading'] ?? 'Default subheading',
        ])->render();
    }
}

The getPreviewLabel() can be defined if you would like to customize the label that is displayed above the preview in the editor. By default, it will use the label defined in the getLabel() method, but the getPreviewLabel() is able to access the $config for the block, allowing you to display dynamic information in the label:

use Filament\Forms\Components\RichEditor\RichContentCustomBlock;

class HeroBlock extends RichContentCustomBlock
{
    // ...

    /**
     * @param  array<string, mixed>  $config
     */
    public static function getPreviewLabel(array $config): string
    {
        return "Hero section: {$config['heading']}";
    }
}

Rendering content with custom blocks

When rendering the rich content, you can pass the array of custom blocks to the RichContentRenderer to ensure that the blocks are rendered correctly:

use Filament\Forms\Components\RichEditor\RichContentRenderer;

RichContentRenderer::make($record->content)
    ->customBlocks([
        HeroBlock::class,
        CallToActionBlock::class,
    ])
    ->toHtml()

Each block class may have a toHtml() method that returns the HTML that should be rendered for that block:

use Filament\Forms\Components\RichEditor\RichContentCustomBlock;

class HeroBlock extends RichContentCustomBlock
{
    // ...

    /**
     * @param  array<string, mixed>  $config
     * @param  array<string, mixed>  $data
     */
    public static function toHtml(array $config, array $data): string
    {
        return view('filament.forms.components.rich-editor.rich-content-custom-blocks.hero.index', [
            'heading' => $config['heading'],
            'subheading' => $config['subheading'],
            'buttonLabel' => 'View category',
            'buttonUrl' => $data['categoryUrl'],
        ])->render();
    }
}

As seen above, the toHtml() method receives two parameters: $config, which contains the configuration data submitted in the modal when the block was inserted, and $data, which contains any additional data that may be needed to render the block. This allows you to access the configuration data and render the block accordingly. The data can be passed in the customBlocks() method:

use Filament\Forms\Components\RichEditor\RichContentRenderer;

RichContentRenderer::make($record->content)
    ->customBlocks([
        HeroBlock::class => [
            'categoryUrl' => $record->category->getUrl(),
        ],
        CallToActionBlock::class,
    ])
    ->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:

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

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:

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:

use Filament\Forms\Components\RichEditor;

RichEditor::make('content')
    ->customBlocks([
        HeroBlock::class,
        CallToActionBlock::class,
    ])
    ->activePanel('customBlocks')

Styling custom block previews with prose

By default, custom block previews are displayed without prose styling to make styling easier. You can enable prose styling for a block’s preview using the shouldApplyProseStylingToPreview() method. This is useful when you want the preview to display with typography styles like headings, paragraphs, and other prose elements:

use Filament\Forms\Components\RichEditor\RichContentCustomBlock;

class HeadingBlock extends RichContentCustomBlock
{
    // ...

    /**
     * @param  array<string, mixed>  $config
     */
    public static function shouldApplyProseStylingToPreview(array $config): bool
    {
        return true;
    }
}

When shouldApplyProseStylingToPreview() returns true, the block’s preview will be styled with the prose typography styles defined in the rich editor, including proper margins, font sizes, and other text formatting. By default, this method returns false, so previews are displayed with minimal styling. You can make this decision based on the block’s configuration, allowing different blocks to have different preview styling:

public static function shouldApplyProseStylingToPreview(array $config): bool
{
    return ($config['useProseStyle'] ?? false) === true;
}

Using merge tags

Merge tags allow the user to insert “placeholders” into their rich content, which can be replaced with dynamic values when the content is rendered. This is useful for inserting things like the current user’s name, or the current date. To register merge tags on an editor, use the mergeTags() method:

use Filament\Forms\Components\RichEditor;

RichEditor::make('content')
    ->mergeTags([
        'name',
        'today',
    ])

Merge tags are surrounded by double curly braces, like {{ name }}. When the content is rendered, these tags will be replaced with the corresponding values. To insert a merge tag into the content, users can start typing {{ to search for a tag to insert. Alternatively, they can click on the “merge tags” tool in the editor’s toolbar, which opens a panel containing all the merge tags. They can then drag a merge tag from the editor’s side panel into the content or click to insert it.

Rendering content with merge tags

When rendering the rich content, you can pass an array of values to replace the merge tags with:

use Filament\Forms\Components\RichEditor\RichContentRenderer;

RichContentRenderer::make($record->content)
    ->mergeTags([
        'name' => $record->user->name,
        'today' => now()->toFormattedDateString(),
    ])
    ->toHtml()

If you have many merge tags or you need to run some logic to determine the values, you can use a function as the value of each merge tag. This function will be called when a merge tag is first encountered in the content, and its result is cached for subsequent tags of the same name:

use Filament\Forms\Components\RichEditor\RichContentRenderer;

RichContentRenderer::make($record->content)
    ->mergeTags([
        'name' => fn (): string => $record->user->name,
        'today' => now()->toFormattedDateString(),
    ])
    ->toHtml()

Using HTML content in merge tags

By default, merge tags render their values as plain text. However, you can render HTML content in merge tags by providing values that implement Laravel’s Htmlable interface. This is useful for inserting formatted content, links, or other HTML elements:

use Filament\Forms\Components\RichEditor\RichContentRenderer;
use Illuminate\Support\HtmlString;

RichContentRenderer::make($record->content)
    ->mergeTags([
        'user_name' => $record->user->name, // Plain text
        'user_profile_link' => new HtmlString('<a href="' . route('profile', $record->user) . '">View Profile</a>'),
    ])
    ->toHtml()

When a merge tag value implements the Htmlable interface (such as HtmlString), the system automatically detects this and renders the HTML content without escaping it. Non-Htmlable values continue to be rendered as plain text for security.

Using custom merge tag labels

You may provide custom labels for merge tags that will be displayed in the editor’s side panel and content preview using an associative array where the keys are the merge tag names and the values are the labels:

use Filament\Forms\Components\RichEditor;

RichEditor::make('content')
    ->mergeTags([
        'name' => 'Full name',
        'today' => 'Today\'s date',
    ])

The labels aren’t saved in the content of the editor and are only used for display purposes.

Opening the merge tags panel by default

If you want the merge tags panel to be open by default when the rich editor is loaded, you can use the activePanel('mergeTags') method:

use Filament\Forms\Components\RichEditor;

RichEditor::make('content')
    ->mergeTags([
        'name',
        'today',
    ])
    ->activePanel('mergeTags')

Using mentions

Mentions allow users to insert references to other records (such as users, issues, or tags) by typing a trigger character. When the user types a trigger character like @, a dropdown appears allowing them to search and select from available options. The selected mention is inserted as a non-editable inline token. To register mentions on an editor, use the mentions() method with one or more MentionProvider instances:

use Filament\Forms\Components\RichEditor;
use Filament\Forms\Components\RichEditor\MentionProvider;

RichEditor::make('content')
    ->mentions([
        MentionProvider::make('@')
            ->items([
                1 => 'Jane Doe',
                2 => 'John Smith',
            ]),
    ])

Each provider is configured with a trigger character (passed to make()) that activates the mention search. You can have multiple providers with different triggers:

use Filament\Forms\Components\RichEditor;
use Filament\Forms\Components\RichEditor\MentionProvider;

RichEditor::make('content')
    ->mentions([
        MentionProvider::make('@')
            ->items([
                1 => 'Jane Doe',
                2 => 'John Smith',
            ]),
        MentionProvider::make('#')
            ->items([
                'bug' => 'Bug',
                'feature' => 'Feature',
            ]),
    ])

Searching mentions from the database

For large datasets, you should fetch results dynamically using getSearchResultsUsing(). The callback receives the search term and should return an array of options with the format [id => label]. When using dynamic search results, only the mention’s id is stored in the content. To display the correct label when the content is loaded, you must also provide getLabelsUsing(). This callback receives an array of IDs and should return an array with the format [id => label]:

use Filament\Forms\Components\RichEditor;
use Filament\Forms\Components\RichEditor\MentionProvider;

RichEditor::make('content')
    ->mentions([
        MentionProvider::make('@')
            ->getSearchResultsUsing(fn (string $search): array => User::query()
                ->where('name', 'like', "%{$search}%")
                ->orderBy('name')
                ->limit(10)
                ->pluck('name', 'id')
                ->all())
            ->getLabelsUsing(fn (array $ids): array => User::query()
                ->whereIn('id', $ids)
                ->pluck('name', 'id')
                ->all()),
    ])

Rendering content with mentions

When rendering the rich content, you can pass the array of mention providers to the RichContentRenderer to ensure that the mentions are rendered correctly. You can make mentions link to a URL when rendered using the url() method. The callback receives the mention’s id and label, and should return a URL string:

use Filament\Forms\Components\RichEditor\MentionProvider;
use Filament\Forms\Components\RichEditor\RichContentRenderer;

RichContentRenderer::make($record->content)
    ->mentions([
        MentionProvider::make('@')
            ->getLabelsUsing(fn (array $ids): array => User::query()
                ->whereIn('id', $ids)
                ->pluck('name', 'id')
                ->all())
            ->url(fn (string $id, string $label): string => route('users.show', $id)),
    ])
    ->toHtml()

The string returned from the url() closure is rendered directly into the href attribute of an <a> tag, so if any part of the URL is built from user input you should make sure it cannot resolve to a scheme like javascript: or data: that the browser would execute. The simplest way to guarantee this is to wrap the return value in Filament’s Str::sanitizeUrl() helper, which only allows http/https and relative URLs:

use Illuminate\Support\Str;

->url(fn (string $id, string $label): ?string => Str::sanitizeUrl(
    route('users.show', $id),
))

If you intentionally want to allow a javascript: URL (for example, to wire a mention to an Alpine.js handler), skip the helper and return the raw value — just make sure none of the components of that URL come from untrusted user input.

Registering rich content attributes

There are elements of the rich editor configuration that apply to both the editor and the renderer. For example, if you are using private images, custom blocks, merge tags, mentions, or plugins, you need to ensure that the same configuration is used in both places. To do this, Filament provides you with a way to register rich content attributes that can be used in both the editor and the renderer. If a plugin implements HasFileAttachmentProvider, the file attachment provider is automatically resolved from the plugin, so you do not need to call fileAttachmentProvider() on the attribute or on the renderer. To register rich content attributes on an Eloquent model, you should use the InteractsWithRichContent trait and implement the HasRichContent interface. This allows you to register the attributes in the setUpRichContent() method:

use Filament\Forms\Components\RichEditor\MentionProvider;
use Filament\Forms\Components\RichEditor\Models\Concerns\InteractsWithRichContent;
use Filament\Forms\Components\RichEditor\Models\Contracts\HasRichContent;
use Illuminate\Database\Eloquent\Model;

class Post extends Model implements HasRichContent
{
    use InteractsWithRichContent;

    public function setUpRichContent(): void
    {
        $this->registerRichContent('content')
            ->fileAttachmentsDisk('s3')
            ->fileAttachmentsVisibility('private')
            ->customBlocks([
                HeroBlock::class => [
                    'categoryUrl' => fn (): string => $this->category->getUrl(),
                ],
                CallToActionBlock::class,
            ])
            ->mergeTags([
                'name' => fn (): string => $this->user->name,
                'today' => now()->toFormattedDateString(),
            ])
            ->mergeTagLabels([
                'name' => 'Full name',
                'today' => 'Today\'s date',
            ])
            ->mentions([
                MentionProvider::make('@')
                    ->items([
                        1 => 'Jane Doe',
                        2 => 'John Smith',
                    ]),
            ])
            ->textColors([
                'brand' => TextColor::make('Brand', '#0ea5e9', darkColor: '#38bdf8'),
            ])
            ->customTextColors()
            ->plugins([
                HighlightRichContentPlugin::make(),
            ]);
    }
}

Whenever you use the RichEditor component, the configuration registered for the corresponding attribute will be used:

use Filament\Forms\Components\RichEditor;

RichEditor::make('content')

To easily render the rich content HTML from a model with the given configuration, you can call the renderRichContent() method on the model, passing the name of the attribute:

{!! $record->renderRichContent('content') !!}

Alternatively, you can get an Htmlable object to render without escaping the HTML:

{{ $record->getRichContentAttribute('content') }}

When using a text column in a table or a text entry in an infolist, you don’t need to manually render the rich content. Filament will do this for you automatically:

use Filament\Infolists\Components\TextEntry;
use Filament\Tables\Columns\TextColumn;

TextColumn::make('content')

TextEntry::make('content')

Extending the rich editor

You can create plugins for the rich editor, which allow you to add custom TipTap extensions to the editor and renderer, as well as custom toolbar buttons. Create a new class that implements the RichContentPlugin interface:

use Filament\Actions\Action;
use Filament\Forms\Components\ColorPicker;
use Filament\Forms\Components\RichEditor;
use Filament\Forms\Components\RichEditor\EditorCommand;
use Filament\Forms\Components\RichEditor\Plugins\Contracts\RichContentPlugin;
use Filament\Forms\Components\RichEditor\RichEditorTool;
use Filament\Support\Enums\Width;
use Filament\Support\Facades\FilamentAsset;
use Filament\Support\Icons\Heroicon;
use Tiptap\Core\Extension;
use Tiptap\Marks\Highlight;

class HighlightRichContentPlugin implements RichContentPlugin
{
    public static function make(): static
    {
        return app(static::class);
    }

    /**
     * @return array<Extension>
     */
    public function getTipTapPhpExtensions(): array
    {
        // This method should return an array of PHP TipTap extension objects.
        // See: https://github.com/ueberdosis/tiptap-php
    
        return [
            app(Highlight::class, [
                'options' => ['multicolor' => true],
            ]),
        ];
    }

    /**
     * @return array<string>
     */
    public function getTipTapJsExtensions(): array
    {
        // This method should return an array of URLs to JavaScript files containing
        // TipTap extensions that should be asynchronously loaded into the editor
        // when the plugin is used.
    
        return [
            FilamentAsset::getScriptSrc('rich-content-plugins/highlight'),
        ];
    }

    /**
     * @return array<RichEditorTool>
     */
    public function getEditorTools(): array
    {
        // This method should return an array of `RichEditorTool` objects, which can then be
        // used in the `toolbarButtons()` of the editor.
        
        // The `jsHandler()` method allows you to access the TipTap editor instance
        // through `$getEditor()`, and `chain()` any TipTap commands to it.
        // See: https://tiptap.dev/docs/editor/api/commands
        
        // The `action()` method allows you to run an action (registered in the `getEditorActions()`
        // method) when the toolbar button is clicked. This allows you to open a modal to
        // collect additional information from the user before running a command.
    
        return [
            RichEditorTool::make('highlight')
                ->jsHandler('$getEditor()?.chain().focus().toggleHighlight().run()')
                ->icon(Heroicon::CursorArrowRays),
            RichEditorTool::make('highlightWithCustomColor')
                ->action(arguments: '{ color: $getEditor().getAttributes(\'highlight\')?.[\'data-color\'] }')
                ->icon(Heroicon::CursorArrowRipple),
        ];
    }

    /**
     * @return array<Action>
     */
    public function getEditorActions(): array
    {
        // This method should return an array of `Action` objects, which can be used by the tools
        // registered in the `getEditorTools()` method. The name of the action should match
        // the name of the tool that uses it.
        
        // The `runCommands()` method allows you to run TipTap commands on the editor instance.
        // It accepts an array of `EditorCommand` objects that define the command to run,
        // as well as any arguments to pass to the command. You should also pass in the
        // `editorSelection` argument, which is the current selection in the editor
        // to apply the commands to.
    
        return [
            Action::make('highlightWithCustomColor')
                ->modalWidth(Width::Large)
                ->fillForm(fn (array $arguments): array => [
                    'color' => $arguments['color'] ?? null,
                ])
                ->schema([
                    ColorPicker::make('color'),
                ])
                ->action(function (array $arguments, array $data, RichEditor $component): void {
                    $component->runCommands(
                        [
                            EditorCommand::make(
                                'toggleHighlight',
                                arguments: [[
                                    'color' => $data['color'],
                                ]],
                            ),
                        ],
                        editorSelection: $arguments['editorSelection'],
                    );
                }),
        ];
    }
}

You can use the plugins() method to register your plugin with the rich editor and rich content renderer:

use Filament\Forms\Components\RichEditor;
use Filament\Forms\Components\RichEditor\RichContentRenderer;

RichEditor::make('content')
    ->toolbarButtons([
        ['bold', 'highlight', 'highlightWithCustomColor'],
        ['h2', 'h3'],
        ['bulletList', 'orderedList'],
    ])
    ->plugins([
        HighlightRichContentPlugin::make(),
    ])

RichContentRenderer::make($record->content)
    ->plugins([
        HighlightRichContentPlugin::make(),
    ])

By default, when a plugin provides tools via getEditorTools(), those tools are registered but not automatically shown in the toolbar. The user needs to manually add them using toolbarButtons() or enableToolbarButtons(). If you want your plugin to automatically enable or disable toolbar buttons, you can implement the HasToolbarButtons interface alongside RichContentPlugin. This is an optional, separate interface:

use Filament\Forms\Components\RichEditor\Plugins\Contracts\HasToolbarButtons;
use Filament\Forms\Components\RichEditor\Plugins\Contracts\RichContentPlugin;

class HighlightRichContentPlugin implements RichContentPlugin, HasToolbarButtons
{
    // ... other methods ...

    /**
     * @return array<string | array<string | array<string>>>
     */
    public function getEnabledToolbarButtons(): array
    {
        return ['highlight', 'highlightWithCustomColor'];
    }

    /**
     * @return array<string>
     */
    public function getDisabledToolbarButtons(): array
    {
        return [];
    }
}

The getEnabledToolbarButtons() method returns button names to add to the toolbar. The getDisabledToolbarButtons() method returns button names to remove from the toolbar. Plugin toolbar modifications are applied before user-level modifications. This means the user can always override the plugin’s behavior using enableToolbarButtons() or disableToolbarButtons():

RichEditor::make('content')
    ->plugins([
        HighlightRichContentPlugin::make(),
    ])
    ->disableToolbarButtons(['highlightWithCustomColor'])

Setting up a TipTap JavaScript extension

Filament is able to asynchronously load JavaScript extensions for TipTap. To do this, you need to create a JavaScript file that contains the extension, and register it in the getTipTapJsExtensions() method of your plugin. For instance, if you wanted to use the TipTap highlight extension, make sure it is installed first:

npm install @tiptap/extension-highlight --save-dev

Then, create a JavaScript file that imports the extension. In this example, create a file called highlight.js in the resources/js/filament/rich-content-plugins directory, and add the following code to it:

import Highlight from '@tiptap/extension-highlight'


export default Highlight.configure({
    multicolor: true,
})

One way to compile this file is to use esbuild. You can install it using npm:

npm install esbuild --save-dev

You must create an esbuild script to compile the file. You can put this anywhere, for example bin/build.js:

import * as esbuild from 'esbuild'

async function compile(options) {
    const context = await esbuild.context(options)

    await context.rebuild()
    await context.dispose()
}

compile({
    define: {
        'process.env.NODE_ENV': `'production'`,
    },
    bundle: true,
    mainFields: ['module', 'main'],
    platform: 'neutral',
    sourcemap: false,
    sourcesContent: false,
    treeShaking: true,
    target: ['es2020'],
    minify: true,
    entryPoints: ['./resources/js/filament/rich-content-plugins/highlight.js'],
    outfile: './resources/js/dist/filament/rich-content-plugins/highlight.js',
})

As you can see at the bottom of the script, we are compiling a file called resources/js/filament/rich-content-plugins/highlight.js into resources/js/dist/filament/rich-content-plugins/highlight.js. You can change these paths to suit your needs. You can compile as many files as you want. To run the script and compile this file into resources/js/dist/filament/rich-content-plugins/highlight.js run the following command:

node bin/build.js

You should register it in the boot() method of a service provider, like AppServiceProvider, and use loadedOnRequest() so that it is not downloaded until the rich editor is loaded on a page:

use Filament\Support\Assets\Js;
use Filament\Support\Facades\FilamentAsset;

FilamentAsset::register([
    Js::make('rich-content-plugins/highlight', __DIR__ . '/../../resources/js/dist/filament/rich-content-plugins/highlight.js')->loadedOnRequest(),
]);

To publish this new JavaScript file into the /public directory of your app so that it can be served, you can use the filament:assets command:

php artisan filament:assets

In the plugin object, the getTipTapJsExtensions() method should return the path to the JavaScript file you just created. Now that it’s registered with FilamentAsset, you can use the getScriptSrc() method to get the URL to the file:

use Filament\Support\Facades\FilamentAsset;

/**
 * @return array<string>
 */
public function getTipTapJsExtensions(): array
{
    return [
        FilamentAsset::getScriptSrc('rich-content-plugins/highlight'),
    ];
}

When custom JavaScript extensions import from @tiptap/core or @tiptap/pm/*, each compiled extension includes its own copy of these packages. This wastes around 150-200 KB per extension and — more importantly — creates multiple ProseMirror instances on the page. Because ProseMirror relies heavily on instanceof checks (for Node, Mark, Plugin, DecorationSet, etc.), extensions that bundle their own copy of these modules can fail to interoperate with the editor’s core. To avoid this, Filament exposes the bundled TipTap and ProseMirror modules on window.FilamentRichEditor.tiptap:

window.FilamentRichEditor.tiptap = {
    core,     // @tiptap/core
    pmState,  // @tiptap/pm/state
    pmView,   // @tiptap/pm/view
    pmModel,  // @tiptap/pm/model
}

You can reference these modules directly in your extension:

const { Node, mergeAttributes } = window.FilamentRichEditor.tiptap.core
const { Plugin, PluginKey } = window.FilamentRichEditor.tiptap.pmState

export default Node.create({
    name: 'myExtension',
    // ...
})

Alternatively, you can configure your build to intercept imports of @tiptap/core and @tiptap/pm/{state,view,model} and resolve them from the global at runtime. This lets you keep writing normal import statements in your extension source — other @tiptap/* packages (like @tiptap/extension-highlight) continue to be bundled as usual. The following esbuild plugin inspects each intercepted package’s real named exports at build time and rewrites the imports to read from window.FilamentRichEditor.tiptap:

npm install --save-dev @tiptap/core @tiptap/pm

// bin/build.js
import * as esbuild from 'esbuild'

const tiptapSharedPlugin = {
    name: 'tiptap-shared',
    setup(build) {
        const keys = {
            '@tiptap/core': 'core',
            '@tiptap/pm/state': 'pmState',
            '@tiptap/pm/view': 'pmView',
            '@tiptap/pm/model': 'pmModel',
        }

        build.onResolve({ filter: /^@tiptap\/(core|pm\/(state|view|model))$/ }, (args) => ({
            path: args.path,
            namespace: 'tiptap-shared',
        }))

        build.onLoad({ filter: /.*/, namespace: 'tiptap-shared' }, async (args) => {
            const realModule = await import(args.path)
            const namedExports = Object.keys(realModule).filter(
                (key) => key !== '__esModule' && key !== 'default',
            )

            const key = keys[args.path]
            let code = `const __module = window.FilamentRichEditor.tiptap.${key};\n`

            if (namedExports.length) {
                code += `export const { ${namedExports.join(', ')} } = __module;\n`
            }

            code += `export default __module?.default ?? __module;\n`

            return { contents: code, loader: 'js' }
        })
    },
}

esbuild.build({
    // ...
    plugins: [tiptapSharedPlugin],
    entryPoints: ['./resources/js/filament/rich-content-plugins/my-extension.js'],
    outfile: './resources/js/dist/filament/rich-content-plugins/my-extension.js',
})

window.FilamentRichEditor.tiptap is assigned when the rich editor bundle loads, which happens before getTipTapJsExtensions() URLs are fetched. If you need to use the modules in a context where the rich editor has not yet loaded, bundle your own copies instead.The esbuild plugin above reads the named exports from your locally-installed @tiptap/core and @tiptap/pm at build time, so keep those versions roughly in sync with the version bundled by Filament — otherwise a newer named export referenced in your extension may be undefined at runtime.

​Introduction

​Storing content as JSON

​Customizing the toolbar buttons

​Customizing floating toolbars

​Grouping toolbar buttons into dropdowns

​Using textual dropdown toolbar buttons

​Customizing text colors

​Rendering rich content

​Styling the rendered content

​Security

​Uploading images to the editor

​Using private images in the editor

​Securing file attachment IDs

​Allowing additional data-id values with a callback

​Validating uploaded images

​Allowing users to resize images

​Using custom blocks

​Rendering a preview for a custom block

​Rendering content with custom blocks

​Grouping custom blocks

​Opening the custom blocks panel by default

​Styling custom block previews with prose

​Using merge tags

​Rendering content with merge tags

​Using HTML content in merge tags

​Using custom merge tag labels

​Opening the merge tags panel by default

​Using mentions

​Searching mentions from the database

​Rendering content with mentions

​Registering rich content attributes

​Extending the rich editor

​Enabling or disabling toolbar buttons from a plugin

​Setting up a TipTap JavaScript extension

​Sharing the bundled TipTap/ProseMirror instance

Introduction

Storing content as JSON

Customizing the toolbar buttons

Customizing floating toolbars

Grouping toolbar buttons into dropdowns

Using textual dropdown toolbar buttons

Customizing text colors

Rendering rich content

Styling the rendered content

Security

Uploading images to the editor

Using private images in the editor

Securing file attachment IDs

Allowing additional `data-id` values with a callback

Validating uploaded images

Allowing users to resize images

Using custom blocks

Rendering a preview for a custom block

Rendering content with custom blocks

Grouping custom blocks

Opening the custom blocks panel by default

Styling custom block previews with prose

Using merge tags

Rendering content with merge tags

Using HTML content in merge tags

Using custom merge tag labels

Opening the merge tags panel by default

Using mentions

Searching mentions from the database

Rendering content with mentions

Registering rich content attributes

Extending the rich editor

Enabling or disabling toolbar buttons from a plugin

Setting up a TipTap JavaScript extension

Sharing the bundled TipTap/ProseMirror instance