### Install Filament Tiptap Editor

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

Install the package via Composer and optionally publish the configuration file.

```bash
composer require awcodes/filament-tiptap-editor:"^3.0"
```

```bash
php artisan vendor:publish --tag="filament-tiptap-editor-config"
```

--------------------------------

### Install Filament Tiptap Editor Package

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Install the package using composer. Ensure you are using version 3.0 or higher.

```bash
composer require awcodes/filament-tiptap-editor:"^3.0"
```

--------------------------------

### Configure Mention Search Strategy

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Set the search strategy for mentions. Defaults to 'starts with'. Use MentionSearchStrategy::Tokenized for multi-keyword matching.

```php
TiptapEditor::make(name: 'content')
    // You can also use MentionSearchStrategy::Tokenized
    ->mentionSearchStrategy(MentionSearchStrategy::StartsWith)
```

--------------------------------

### Livewire Component Setup for Standalone Forms

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

This Livewire component demonstrates the setup for using TiptapEditor in a standalone form. It includes form schema definition and state management for saving post content.

```php
// Livewire component
use Filament\Forms\Concerns\InteractsWithForms;
use Filament\Forms\Contracts\HasForms;

class EditPost extends Component implements HasForms
{
    use InteractsWithForms;

    public ?array $data = [];

    public function mount(Post $post): void
    {
        $this->form->fill($post->toArray());
    }

    public function form(Form $form): Form
    {
        return $form
            ->schema([
                TiptapEditor::make('content')->required(),
            ])
            ->statePath('data');
    }

    public function save(): void
    {
        Post::find($this->post->id)->update($this->form->getState());
    }
}
```

--------------------------------

### Create Custom Tiptap Node Extension (JS)

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

Define a custom Tiptap node extension in JavaScript. This example shows how to create a 'banner' node with specific parsing and rendering logic.

```javascript
// resources/js/tiptap/banner.js
import { Node, mergeAttributes } from "@tiptap/core";

const Banner = Node.create({
    name: "banner",
    group: "block",
    content: "inline*",
    parseHTML() { return [{ tag: 'div[data-type="banner"]' }]; },
    renderHTML({ HTMLAttributes }) {
        return ["div", mergeAttributes({ "data-type": "banner" }, HTMLAttributes), 0];
    },
});
export default Banner;
```

```javascript
// resources/js/tiptap/extensions.js
import Banner from "./banner.js";
window.TiptapEditorExtensions = { banner: [Banner] };
```

--------------------------------

### Configure Database Column and Model Casting for JSON Output

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Example of how to set the database column type to JSON and cast it in the model when using JSON output format.

```php
// in your migration
$table->json('content');

// in your model
protected $casts = [
    'content' => 'json' // or 'array'
];
```

--------------------------------

### Configure Tiptap Editor Field

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Example of how to use the TiptapEditor field in a Filament form. Customize profile, tools, disk, directory, accepted file types, max size, output format, and content width.

```php
use FilamentTiptapEditor\TiptapEditor;
use FilamentTiptapEditor\Enums\TiptapOutput;

TiptapEditor::make('content')
    ->profile('default|simple|minimal|none|custom')
    ->tools([]) // individual tools to use in the editor, overwrites profile
    ->disk('string') // optional, defaults to config setting
    ->directory('string or Closure returning a string') // optional, defaults to config setting
    ->acceptedFileTypes(['array of file types']) // optional, defaults to config setting
    ->maxSize('integer in KB') // optional, defaults to config setting
    ->output(TiptapOutput::Html) // optional, change the format for saved data, default is html
    ->maxContentWidth('5xl')
    ->required();
```

--------------------------------

### Collapse Blocks Panel in TiptapEditor

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Configure the Tiptap editor to start with the blocks panel collapsed using `collapseBlocksPanel()`.

```php
use App\TiptapBlocks\BatmanBlock;
use App\TiptapBlocks\StaticBlock;
use FilamentTiptapEditor\TiptapEditor;

TiptapEditor::configureUsing(function (TiptapEditor $component) {
    $component
        ->collapseBlocksPanel()
        ->blocks([...]);
});
```

--------------------------------

### Configure Toolbar Profiles

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

Select a pre-defined toolbar profile or override tools on a per-instance basis. Custom profiles can be defined in the configuration file.

```php
use FilamentTiptapEditor\TiptapEditor;

// Use a built-in profile
TiptapEditor::make('body')->profile('simple');

// Override tools on a per-instance basis (ignores profile)
TiptapEditor::make('excerpt')
    ->tools(['bold', 'italic', 'link', 'bullet-list']);

// config/filament-tiptap-editor.php — define a custom profile
'profiles' => [
    'blog' => [
        'heading', 'bold', 'italic', 'strike', '|',
        'bullet-list', 'ordered-list', 'blockquote', '|',
        'link', 'media', 'code-block',
    ],
],

// Use the custom profile
TiptapEditor::make('content')->profile('blog'),
```

--------------------------------

### Configure Media Uploads in Tiptap Editor

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

Customize media upload settings like disk, directory, accepted file types, and size limits. These can be set globally in config or overridden per instance.

```php
use FilamentTiptapEditor\TiptapEditor;

TiptapEditor::make('content')
    ->disk('s3')
    ->directory('uploads/posts')
    ->visibility('public')
    ->acceptedFileTypes(['image/jpeg', 'image/png', 'image/webp', 'image/gif'])
    ->maxSize(4096)          // KB
    ->minSize(10)
    ->preserveFileNames(true)
    ->imageCropAspectRatio('16:9')
    ->imageResizeTargetWidth('1280')
    ->imageResizeTargetHeight('720');
```

```php
// config/filament-tiptap-editor.php equivalent
return [
    'disk'                      => 's3',
    'directory'                 => 'uploads/posts',
    'visibility'                => 'public',
    'accepted_file_types'       => ['image/jpeg', 'image/png', 'image/webp'],
    'max_file_size'             => 4096,
    'preserve_file_names'       => false,
    'image_crop_aspect_ratio'   => null,
    'image_resize_target_width' => null,
    'image_resize_target_height'=> null,
];
```

--------------------------------

### Create a Custom Tiptap Block Class

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Define a custom block by extending `TiptapBlock`. Specify the preview and rendered blade file paths. Implement `getFormSchema()` to define the block's settings, or omit it for static blocks without settings.

```php
use FilamentTiptapEditor\TiptapBlock;

class BatmanBlock extends TiptapBlock
{
    public string $preview = 'blocks.previews.batman';

    public string $rendered = 'blocks.rendered.batman';

    public function getFormSchema(): array
    {
        return [
            TextInput::make('name'),
            TextInput::make('color'),
            Select::make('side')
                ->options([
                    'Hero' => 'Hero',
                    'Villain' => 'Villain',
                ])
                ->default('Hero')
        ];
    }
}
```

```php
use FilamentTiptapEditor\TiptapBlock;

class StaticBlock extends TiptapBlock
{
    public string $preview = 'blocks.previews.static';

    public string $rendered = 'blocks.rendered.static';
}
```

```php
class BatmanBlock extends TiptapBlock
{
    public string $width = 'xl';
    
    public bool $slideOver = true;
    
    public ?string $icon = 'heroicon-o-film';
}
```

--------------------------------

### Configure Media Upload Settings

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Set accepted file types, disk, directory, visibility, and other options for media uploads.

```php
[
    'accepted_file_types' => ['image/jpeg', 'image/png', 'image/webp', 'image/svg+xml', 'application/pdf'],
    'disk' => 'public',
    'directory' => 'images',
    'visibility' => 'public',
    'preserve_file_names' => false,
    'max_file_size' => 2042,
    'image_crop_aspect_ratio' => null,
    'image_resize_target_width' => null,
    'image_resize_target_height' => null,
]
```

--------------------------------

### Enable RTL Support

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Set the 'direction' key in the configuration to 'rtl' to ensure proper alignment for RTL languages.

```php
// config/filament-tiptap-editor.php
'direction' => 'rtl'
```

--------------------------------

### Generate Fake Tiptap Content with TiptapFaker (HTML)

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

Utilize the TiptapFaker fluent builder to generate realistic fake Tiptap content in HTML format for database seeders and tests. Chain methods to construct complex documents.

```php
use FilamentTiptapEditor\TiptapFaker;

// Chainable builder — generate a full-featured document
$html = TiptapFaker::make()
    ->heading(level: 1)
    ->paragraphs(count: 2, withRandomLinks: true)
    ->unorderedList(count: 4)
    ->image(width: 800, height: 450)
    ->blockquote()
    ->code()
    ->table(cols: 4)
    ->hr()
    ->video(provider: 'youtube', responsive: true)
    ->asHTML();

// Generate everything at once with ->sink()
$fullDoc = TiptapFaker::make()->sink()->asHTML();
```

--------------------------------

### Publish Configuration File

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Publish the plugin's configuration file using the Artisan command if you need to modify default settings.

```bash
php artisan vendor:publish --tag="filament-tiptap-editor-config"
```

--------------------------------

### Configure Grid Builder Layouts in Tiptap Editor

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

Define the available layout presets for the grid-builder tool. Users can then select from these presets to create multi-column layouts.

```php
use FilamentTiptapEditor\TiptapEditor;

TiptapEditor::make('content')
    ->gridLayouts([
        'two-columns',
        'three-columns',
        'asymmetric-left-thirds',
        'asymmetric-right-thirds',
        'fixed-two-columns',
        'fixed-three-columns',
    ]);

// All available layout keys (default set):
// two-columns, three-columns, four-columns, five-columns
// fixed-two-columns, fixed-three-columns, fixed-four-columns, fixed-five-columns
// asymmetric-left-thirds, asymmetric-right-thirds
// asymmetric-left-fourths, asymmetric-right-fourths
```

--------------------------------

### Configure Dynamic Mentions in Tiptap Editor

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

Fetch mention items dynamically using a closure that accepts a search query. Requires the HasFormMentions trait on the Livewire component. Configure debouncing and placeholder messages.

```php
use FilamentTiptapEditor\Concerns\HasFormMentions;
use FilamentTiptapEditor\TiptapEditor;
use FilamentTiptapEditor\Data\MentionItem;

// In your Livewire page/resource class:
class EditPost extends EditRecord {
    use HasFormMentions;
}

// On the field:
TiptapEditor::make('content')
    ->getMentionItemsUsing(function (string $query) {
        return User::search($query)
            ->limit(5)
            ->get()
            ->map(fn ($u) => new MentionItem(id: $u->id, label: $u->name, image: $u->avatar_url))
            ->toArray();
    })
    ->mentionDebounce(debounceInMs: 300)
    ->mentionItemsPlaceholder('Search users…')
    ->mentionItemsLoading('Searching…');
```

--------------------------------

### Define Editor Tool Profiles

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Configure different sets of tools available in the editor. Use a pipe '|' to separate tools into groups. The 'default' profile includes all available tools.

```php
'profiles' => [
    'default' => [
        'heading', 'bullet-list', 'ordered-list', 'checked-list', 'blockquote', 'hr',
        'bold', 'italic', 'strike', 'underline', 'superscript', 'subscript', 'lead', 'small', 'align-left', 'align-center', 'align-right',
        'link', 'media', 'oembed', 'table', 'grid-builder', 'details',
        'code', 'code-block', 'source',
    ],
    'simple' => [
        'heading', 'hr', 'bullet-list', 'ordered-list', 'checked-list',
        'bold', 'italic', 'lead', 'small',
        'link', 'media',
    ],
    'minimal' => [
        'bold', 'italic', 'link', 'bullet-list', 'ordered-list',
    ],
],
```

--------------------------------

### Add Image Prefixes to Mention Items

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Include an 'image' URL to display an image as a prefix for mention items. Use 'roundedImage: true' for avatars.

```php
TiptapEditor::make(name: 'content')
    ->mentionItems([
        new MentionItem(id: 1, label: 'John Doe', image: 'YOUR_IMAGE_URL'),
        
        // Optional: Show rounded image, useful for avatars
        new MentionItem(id: 1, label: 'John Doe', image: 'YOUR_IMAGE_URL', roundedImage: true)
    ])
```

--------------------------------

### Implement Dynamic Mention Item Loading

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Use the getMentionItemsUsing method to dynamically fetch and format mention suggestions based on a search query.

```php
TiptapEditor::make(name: 'content')
    ->getMentionItemsUsing(function (string $query) {
        // Get suggestions based of the $query
        return User::search($query)->get()->map(fn ($user) => new MentionItem(
            id: $user->id,
            label: $user->name
        ))->take(5)->toArray();
    })
```

--------------------------------

### Create PHP Parser for Custom Extension

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Develop a PHP class that extends `Tiptap\Core\Node` to handle the server-side parsing and rendering of your custom extension's content. Place this in your application's `app/TiptapExtensions` directory.

```php
namespace App\TiptapExtensions;

use Tiptap\Core\Node;

class Hero extends Node
{
    public static $name = 'hero';
    ...
}
```

--------------------------------

### Register Custom Tiptap Blocks Globally or Per-Instance

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

Register custom blocks either globally using configureUsing() in a ServiceProvider or on a per-instance basis using the blocks() method on the TiptapEditor.

```php
// Register blocks globally in a ServiceProvider
use App\TiptapBlocks\CalloutBlock;
use FilamentTiptapEditor\TiptapEditor;

TiptapEditor::configureUsing(function (TiptapEditor $component) {
    $component
        ->output(\FilamentTiptapEditor\Enums\TiptapOutput::Json)
        ->collapseBlocksPanel(false)
        ->blocks([CalloutBlock::class]);
});

// Or per-instance
TiptapEditor::make('content')
    ->output(\FilamentTiptapEditor\Enums\TiptapOutput::Json)
    ->blocks([CalloutBlock::class]);
```

--------------------------------

### Set Node-Specific Placeholders

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Configure distinct placeholder texts for different node types within the Tiptap editor.

```php
TiptapEditor::make('content')
    ->nodePlaceholders([
        'paragraph' => 'Start writing your paragraph...',
        'heading' => 'Insert a heading...',
    ])
```

--------------------------------

### Configure Static Mentions in Tiptap Editor

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

Define static mention items directly using an array of MentionItem objects. Configure the trigger character, search strategy, and display limits.

```php
use FilamentTiptapEditor\TiptapEditor;
use FilamentTiptapEditor\Data\MentionItem;
use FilamentTiptapEditor\Enums\MentionSearchStrategy;

TiptapEditor::make('content')
    ->mentionItems([
        new MentionItem(id: 1, label: 'Alice',   href: '/users/1', image: '/avatars/1.jpg', roundedImage: true),
        new MentionItem(id: 2, label: 'Bob',     href: '/users/2'),
        new MentionItem(id: 3, label: 'Charlie', data: ['role' => 'admin']),
    ])
    ->mentionTrigger('@')                                    // default '@'
    ->mentionSearchStrategy(MentionSearchStrategy::StartsWith) // or Tokenized
    ->maxMentionItems(5)
    ->emptyMentionItemsMessage('No users found');
```

--------------------------------

### Rebuild Custom Theme

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

After updating configuration files, rebuild your custom theme using npm.

```sh
npm run build
```

--------------------------------

### Configure Bubble and Floating Menus in Tiptap Editor

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

Control the visibility and tools available in the bubble menu (on selection) and floating menu (on empty lines). Customize tippy.js placement.

```php
use FilamentTiptapEditor\TiptapEditor;
use FilamentTiptapEditor\Enums\TippyPlacement;

TiptapEditor::make('content')
    ->disableBubbleMenus()                          // hide bubble menu
    ->disableFloatingMenus()                        // hide floating menu
    ->bubbleMenuTools(['bold', 'italic', 'link'])
    ->floatingMenuTools(['media', 'table', 'code-block'])
    ->tippyPlacement(TippyPlacement::Bottom);       // Auto|Top|Bottom|Left|Right
```

```php
// config/filament-tiptap-editor.php defaults
'disable_bubble_menus'   => false,
'disable_floating_menus' => false,
'bubble_menu_tools'      => ['bold', 'italic', 'strike', 'underline', 'superscript', 'subscript', 'lead', 'small', 'link'],
'floating_menu_tools'    => ['media', 'grid-builder', 'details', 'table', 'oembed', 'code-block', 'blocks'],
```

--------------------------------

### Register Custom Extension in Config

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Register your custom extension by adding its ID to a profile (e.g., 'minimal'), specifying the paths for the extensions script and styles, and defining the extension's details including its ID, name, button component, and PHP parser.

```php
'profiles' => [
    'minimal' => [
        ..., 
        'hero',
    ],
],
'extensions_script' => 'resources/js/tiptap/extensions.js',
'extensions_styles' => 'resources/css/tiptap/extensions.css',
'extensions' => [
    [
        'id' => 'hero',
        'name' => 'Hero',
        'button' => 'tools.hero',
        'parser' => \App\TiptapExtensions\Hero::class,
    ],
],
```

--------------------------------

### Implement Toolbar Button View

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Create a Blade view for your custom extension's toolbar button, typically located in `resources/views/components`. Use the `filament-tiptap-editor::button` component for consistency and define its label, active state, and action.

```blade
<x-filament-tiptap-editor::button
    label="Hero"
    active="hero"
    action="editor().commands.toggleHero()"
>
    <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24"><path fill="currentColor" d="M5 21q-.825 0-1.413-.588T3 19V5q0-.825.588-1.413T5 3h14q.825 0 1.413.588T21 5v14q0 .825-.588 1.413T19 21H5Zm0-2h14v-5H5v5Z"/></svg>
    
    <span class="sr-only">{{ $label }}</span>
</x-filament-tiptap-editor::button>
```

--------------------------------

### Configure Vite for Extension Assets

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Add your extension's JavaScript and CSS files to the Vite build process by including them in the `laravel.input` array in your `vite.config.js`.

```javascript
export default defineConfig({
    plugins: [
        laravel({
            input: [
                ...
                'resources/js/tiptap/extensions.js',
                'resources/css/tiptap/extensions.css',
            ],
            refresh: true,
        }),
    ],
});
```

--------------------------------

### Set Per-Instance Max Content Width

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Configure the maximum content width for a specific editor instance using the '->maxContentWidth()' method.

```php
use FilamentTiptapEditor\TiptapEditor;

TiptapEditor::make('content')
    ->maxContentWidth('3xl');
```

--------------------------------

### Define Preset Colors for ColorPicker

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

Configure predefined hex colors to be displayed as swatches in the color picker toolbar. These are defined solely within the configuration file.

```php
// config/filament-tiptap-editor.php
'preset_colors' => [
    'primary'   => '#6366f1',
    'secondary' => '#14b8a6',
    'danger'    => '#ef4444',
    'warning'   => '#f59e0b',
    'success'   => '#22c55e',
],
```

--------------------------------

### Configure Tippy Toolbar Placement

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Control the placement of the tippy toolbar by using the `tippyPlacement()` method with an enum value from `TippyPlacement`.

```php
TiptapEditor::make('content')
    ->tippyPlacement(TippyPlacement::Left)
```

--------------------------------

### Define Custom Tiptap Node Extension (JS)

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Create a custom Tiptap Node extension in JavaScript, defining its name and behavior. Ensure it's exported.

```javascript
import { Node, mergeAttributes } from "@tiptap/core";

const Hero = Node.create({
    name: "hero",
    ...
})

export default Hero
```

--------------------------------

### Configure Custom Extensions in Filament

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

Configure the Filament Tiptap Editor to use custom extensions. This includes specifying the profile, script path, styles, and the extension's parser.

```php
// config/filament-tiptap-editor.php
'profiles' => [
    'default' => [..., 'banner'],
],
'extensions_script' => 'resources/js/tiptap/extensions.js',
'extensions_styles'  => 'resources/css/tiptap/extensions.css',
'extensions' => [
    [
        'id'     => 'banner',
        'name'   => 'Banner',
        'button' => 'components.tiptap-buttons.banner',
        'parser' => \App\TiptapExtensions\Banner::class,
    ],
],
```

--------------------------------

### Configure Editor Direction and Content Width

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

Set the global text direction (LTR or RTL) and the maximum content width for the editor. These can be overridden on a per-instance basis.

```php
// config/filament-tiptap-editor.php
'direction'         => 'rtl',  // 'ltr' (default) or 'rtl'
'max_content_width' => 'full', // any Tailwind max-width key or 'full'
```

```php
// Per-instance override
TiptapEditor::make('content')
    ->maxContentWidth('3xl');
```

```php
// Initial height via extra attributes
TiptapEditor::make('content')
    ->extraInputAttributes(['style' => 'min-height: 16rem;']);
```

--------------------------------

### Define a Custom TiptapBlock in PHP

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

Create a custom block by extending TiptapBlock and defining its preview, rendered views, width, and form schema. This allows for structured, reusable content units.

```php
// app/TiptapBlocks/CalloutBlock.php
namespace App\TiptapBlocks;

use Filament\Forms\Components\Select;
use Filament\Forms\Components\Textarea;
use FilamentTiptapEditor\TiptapBlock;

class CalloutBlock extends TiptapBlock
{
    public string $preview  = 'blocks.previews.callout';
    public string $rendered = 'blocks.rendered.callout';
    public string $width    = 'md';
    public bool   $slideOver = false;
    public ?string $icon    = 'heroicon-o-information-circle';

    public function getFormSchema(): array
    {
        return [
            Select::make('type')
                ->options(['info' => 'Info', 'warning' => 'Warning', 'danger' => 'Danger'])
                ->default('info'),
            Textarea::make('message')->required(),
        ];
    }
}
```

--------------------------------

### Set Placeholder for TiptapEditor

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Define a simple placeholder text for the editor content using the `placeholder()` method.

```php
TiptapEditor::make('content')
    ->placeholder('Write something...')
```

--------------------------------

### Add Custom Tiptap Extension Styles (CSS)

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Define CSS styles for your custom Tiptap extensions in `resources/css/tiptap/extensions.css`, scoping them to the `.tiptap-content` parent class.

```css
.tiptap-content {
    .hero-block {
        ...
    }
}
```

--------------------------------

### Configure Output Format

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

Control the format in which editor content is persisted to the database using the TiptapOutput enum (Html, Json, Text). When storing as JSON, ensure the migration column is 'json' and the model cast is 'array' or 'json'.

```php
use FilamentTiptapEditor\TiptapEditor;
use FilamentTiptapEditor\Enums\TiptapOutput;

// Store as JSON (required for Custom Blocks and Merge Tags)
TiptapEditor::make('content')
    ->output(TiptapOutput::Json);

// Corresponding migration column and model cast
// Migration:
$table->json('content');

// Model:
protected $casts = [
    'content' => 'array', // or 'json'
];
```

--------------------------------

### Add Static Mention Items with Arrays

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Alternatively, use simple arrays to define static mention suggestions, each with a 'label' and 'id'.

```php
TiptapEditor::make(name: 'content')
    ->mentionItems([
        ['label' => 'Apple', 'id' => 1],
        ['label' => 'Banana', 'id' => 2],
        ['label' => 'Strawberry', 'id' => 3]
    ])
```

--------------------------------

### Customize Floating Menu Tools

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Specify custom tools to be included in the floating menu using the `floatingMenuTools()` method. The default tools can be overridden via the configuration file.

```php
TiptapEditor::make('content')
    ->floatingMenuTools(['grid-builder', 'media', 'link'])
```

```php
'floating_menu_tools' => ['media', 'grid-builder', 'details', 'table', 'oembed', 'code-block'],
'bubble_menu_tools' => ['bold', 'italic', 'strike', 'underline', 'superscript', 'subscript', 'lead', 'small', 'link'],
```

--------------------------------

### Custom Block Preview Blade View

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Create a preview blade view for your custom block. This view renders the block's content within the editor. Note that Livewire components are not supported in block previews due to `wire:ignore`.

```html
<div class="flex items-center gap-6">
    <div class="text-5xl">
        @php
            echo match($name) {
                'robin' => '🐤',
                'ivy' => '🥀',
                'joker' => '🤡',
                default => '🦇'
            }
        @endphp
    </div>
    <div>
        <p>Name: {{ $name }}</p>
        <p style="color: {{ $color }};">Color: {{ $color }}</p>
        <p>Side: {{ $side ?? 'Good' }}</p>
    </div>
</div>
```

--------------------------------

### Render HTML with Merge Tags Substituted

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

Use the tiptap_converter() with mergeTagsMap() to substitute placeholder tokens in JSON content with actual values before rendering as HTML.

```blade
{{-- Render with values substituted --}}
{!! tiptap_converter()
    ->mergeTagsMap([
        'first_name' => 'Jane',
        'last_name'  => 'Smith',
        'company'    => 'Acme Corp',
    ])
    ->asHTML($emailTemplate->content) !!}
```

--------------------------------

### Set Initial Editor Height

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Use `extraInputAttributes()` to set the minimum height of the editor field. This is useful for controlling the initial visual space the editor occupies.

```php
TiptapEditor::make('content')
    ->extraInputAttributes(['style' => 'min-height: 12rem;'])
```

--------------------------------

### Define Custom Grid Layouts

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Customize the available layouts in the grid tool's dropdown by passing an array of layout names to the `gridLayouts()` method.

```php
TiptapEditor::make('content')
    ->gridLayouts([
        'two-columns',
        'three-columns',
        'four-columns',
        'five-columns',
        'fixed-two-columns',
        'fixed-three-columns',
        'fixed-four-columns',
        'fixed-five-columns',
        'asymmetric-left-thirds',
        'asymmetric-right-thirds',
        'asymmetric-left-fourths',
        'asymmetric-right-fourths',
    ])
```

--------------------------------

### Render a Livewire Component Block

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Use Blade files to render custom blocks, including Livewire components, passing block data as props.

```html
<div>
    <livewire:batman-block
        :name="$name"
        :color="$color"
        :side="$side"
    />
</div>
```

--------------------------------

### Configure Preset Colors

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Define custom hexadecimal color values in the `preset_colors` configuration key to offer a selection of predefined colors in the ColorPicker.

```php
'preset_colors' => [
    'primary' => '#f59e0b',
    'secondary' => '#14b8a6',
    'red' => '#ef4444',
    //..
]
```

--------------------------------

### Register Custom Tiptap Extensions (JS)

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Register your custom JavaScript Tiptap extensions in `resources/js/tiptap/extensions.js` using a key-value pair format.

```javascript
import Hero from "./hero.js";

window.TiptapEditorExtensions = {
    hero: [Hero]
}
```

--------------------------------

### Customize Mention Feature Options

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Configure messages for empty results, placeholders, loading states, and adjust the maximum number of displayed items or the trigger character.

```php
TiptapEditor::make(name: 'content')
    // Customize the "No results found" message
    ->emptyMentionItemsMessage("No users found")
    
    // Set a custom placeholder message. Note: if you set a placeholder, then it will ONLY show suggestions when the query is not empty.
    ->mentionItemsPlaceholder("Search for users...")
    
    // Set a custom loading message. This will be displayed instead of a loading spinner.
    ->mentionItemsLoading("Loading...")
    
    // Customize how many mention items should be shown at once, 8 by default. Is nullable and only works with static suggestions.
    ->maxMentionItems()

    // Set a custom character trigger for mentioning. This is '@' by default
    ->mentionTrigger('#')
```

--------------------------------

### Add Static Mention Items with MentionItem

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Use MentionItem objects to define static mention suggestions with labels, IDs, and optional href or additional data.

```php
TiptapEditor::make(name: 'content')
    ->mentionItems([
        // The simplest mention item: a label and a id
        new MentionItem(label: 'Banana', id: 1),
        
         // Add a href to make the mention clickable in the final HTML output
        new MentionItem(id: 1, label: 'Strawberry', href: 'https://filamentphp.com'),
        
        // Include additional data to be stored in the final JSON output
        new MentionItem(id: 1, label: 'Strawberry', data: ['type' => 'fruit_mentions'])
    ])
```

--------------------------------

### Generate Fake Tiptap Content with TiptapFaker (JSON)

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

Generate fake Tiptap content in JSON format using TiptapFaker, suitable for JSON-typed database columns. The `asJSON()` method can return decoded PHP arrays or raw JSON strings.

```php
// Get JSON output for JSON-typed columns
$json = TiptapFaker::make()
    ->heading()
    ->paragraphs(3)
    ->asJSON(decoded: false); // decoded: true returns PHP array

// Use in a factory
public function definition(): array
{
    return [
        'content' => TiptapFaker::make()->sink()->asJSON(),
    ];
}
```

--------------------------------

### Import Plugin Stylesheet

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Import the plugin's stylesheet into your custom theme's CSS file. This is necessary for the editor's styling to apply correctly.

```css
@import '<path-to-vendor>/awcodes/filament-tiptap-editor/resources/css/plugin.css';
```

--------------------------------

### Register Custom Tiptap Node Extension (PHP)

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

Register a custom Tiptap node extension in PHP. This involves defining the node's properties and how it's parsed and rendered from HTML.

```php
// app/TiptapExtensions/Banner.php
namespace App\TiptapExtensions;

use Tiptap\Core\Node;

class Banner extends Node
{
    public static $name = 'banner';

    public function addOptions(): array { return []; }

    public function parseHTML(): array
    {
        return [['tag' => 'div[data-type="banner"]']];
    }

    public function renderHTML(array $node, array $HTMLAttributes = []): array
    {
        return ['div', array_merge(['data-type' => 'banner'], $HTMLAttributes), 0];
    }
}
```

--------------------------------

### Render Merge Tags as HTML

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Use the `tiptap_converter` helper to map merge tags to specific data and render the content as HTML.

```blade
{!! tiptap_converter()->mergeTagsMap(['first_name' => 'John', 'last_name' => 'Doe'])->asHTML($content) !!}
```

--------------------------------

### Configure Tailwind CSS

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Add the plugin's views to your `tailwind.config.js` file to ensure Tailwind processes the editor's components.

```js
content: [
    ...
    '<path-to-vendor>/awcodes/filament-tiptap-editor/resources/**/*.blade.php',
]
```

--------------------------------

### Render HTML with Table of Contents using TiptapConverter

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

The asHTML() method can inject anchor links into headings and generate a table of contents. Use the toc flag and maxDepth to control heading levels included.

```blade
{{-- Render HTML with anchor links on headings up to h3 --}}
{!! tiptap_converter()->asHTML($post->content, toc: true, maxDepth: 3) !!}
```

```blade
{{-- Generate a standalone nested <ul> TOC --}}
{!! tiptap_converter()->asToc($post->content, maxDepth: 2) !!}
```

```blade
{{-- Generate TOC as a nested PHP array --}}
@php $headings = tiptap_converter()->asTOC($post->content, maxDepth: 3, array: true); @endphp
{{-- $headings example: [['id'=>'intro','text'=>'Intro','depth'=>2,'subs'=>[...]]] --}}
```

```blade
{{-- Use the built-in Blade component --}}
<x-filament-tiptap-editor::table-of-contents
    :headings="tiptap_converter()->asTOC($page->body, array: true)"
/>
```

--------------------------------

### Enable Dynamic Mentions with Trait

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Add the HasFormMentions trait to your Livewire component to enable dynamic loading of mentionable items.

```php
use FilamentTiptapEditor\Concerns\HasFormMentions;

class YourClass
{
use HasFormMentions;
```

--------------------------------

### Register Custom Blocks with TiptapEditor

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Add custom block classes to the Tiptap editor configuration within a service provider's register method.

```php
use App\TiptapBlocks\BatmanBlock;
use App\TiptapBlocks\StaticBlock;
use FilamentTiptapEditor\TiptapEditor;

TiptapEditor::configureUsing(function (TiptapEditor $component) {
    $component
        ->blocks([
            BatmanBlock::class,
            StaticBlock::class,
        ]);
});
```

--------------------------------

### Define Merge Tags on TiptapEditor Field

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

Configure a TiptapEditor instance to use JSON output and define available merge tags. This allows for dynamic content replacement during rendering.

```php
use FilamentTiptapEditor";
use FilamentTiptapEditor\
```

```php
use FilamentTiptapEditor\TiptapEditor;
use FilamentTiptapEditor\Enums\TiptapOutput;

// Define merge tags on the editor field
TiptapEditor::make('email_template')
    ->output(TiptapOutput::Json)
    ->mergeTags(['first_name', 'last_name', 'company'])
    ->showMergeTagsInBlocksPanel(true); // show draggable tags in side panel (default: true)
```

--------------------------------

### Custom Blocks - TiptapBlock

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

Custom blocks allow for reusable, structured content units within the editor, exclusively using JSON output. Each custom block requires a PHP class extending `TiptapBlock`, a Blade preview view, and a Blade rendered view.

```APIDOC
## Custom Blocks — TiptapBlock

Custom blocks are reusable, structured content units embedded in the editor (JSON only). Each block requires a PHP class extending `TiptapBlock`, a Blade preview view, and a Blade rendered view.

```php
// app/TiptapBlocks/CalloutBlock.php
namespace App	yardoc	TiptapBlocks;

use Filament	yardoc	Forms	yardoc	Components	yardoc	Select;
use Filament	yardoc	Forms	yardoc	Components	yardoc	Textarea;
use FilamentTiptapEditor	yardoc	TiptapBlock;

class CalloutBlock extends TiptapBlock
{
    public string $preview  = 'blocks.previews.callout';
    public string $rendered = 'blocks.rendered.callout';
    public string $width    = 'md';
    public bool   $slideOver = false;
    public ?string $icon    = 'heroicon-o-information-circle';

    public function getFormSchema(): array
    {
        return [
            Select::make('type')
                ->options(['info' => 'Info', 'warning' => 'Warning', 'danger' => 'Danger'])
                ->default('info'),
            Textarea::make('message')->required(),
        ];
    }
}
```

```blade
{{-- resources/views/blocks/previews/callout.blade.php --}}
<div class="rounded border-l-4 p-4 {{ $type === 'danger' ? 'border-red-500' : 'border-blue-500' }}">
    <p class="font-bold uppercase text-xs">{{ $type }}</p>
    <p>{{ $message }}</p>
</div>

{{-- resources/views/blocks/rendered/callout.blade.php --}}
<div class="callout callout--{{ $type }}">
    <p>{{ $message }}</p>
</div>
```

```php
// Register blocks globally in a ServiceProvider
use App	yardoc	TiptapBlocks	yardoc	CalloutBlock;
use FilamentTiptapEditor	yardoc	TiptapEditor;

TiptapEditor::configureUsing(function (TiptapEditor $component) {
    $component
        ->output(ilamettiptapeditor	yardoc	Enums	yardoc	TiptapOutput::Json)
        ->collapseBlocksPanel(false)
        ->blocks([CalloutBlock::class]);
});

// Or per-instance
TiptapEditor::make('content')
    ->output(ilamettiptapeditor	yardoc	Enums	yardoc	TiptapOutput::Json)
    ->blocks([CalloutBlock::class]);
```
```

--------------------------------

### tiptap_converter() - Content Conversion Helper

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

The global `tiptap_converter()` helper provides access to the TiptapConverter service for converting stored Tiptap content (HTML, JSON, or text) into different output formats. It's commonly used in Blade views to render content.

```APIDOC
## tiptap_converter() — Content Conversion Helper

The global `tiptap_converter()` helper returns the `TiptapConverter` service, which converts stored Tiptap content (HTML, JSON, or text string) into any of the three output formats. Used primarily in Blade views to render stored content.

```blade
{{-- Render stored content as HTML --}}
{!! tiptap_converter()->asHTML($post->content) !!}

{{-- Render as JSON string --}}
{!! tiptap_converter()->asJSON($post->content) !!}

{{-- Render as plain text (strips all markup) --}}
{{ tiptap_converter()->asText($post->content) }}

{{-- Convert between formats in PHP --}}
$html    = tiptap_converter()->asHTML($post->content);
$json    = tiptap_converter()->asJSON($post->content, decoded: false); // JSON string
$array   = tiptap_converter()->asJSON($post->content, decoded: true);  // PHP array
$text    = tiptap_converter()->asText($post->content);
```
```

--------------------------------

### Render Modals in Standalone Forms

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

When using TiptapEditor outside a Filament Panel with the standalone Forms package, include {{ $this->modal }} in your Livewire view to render modal actions like media and link pickers.

```blade
{{-- resources/views/livewire/edit-post.blade.php --}}
<form wire:submit.prevent="save">
    {{ $this->form }}

    <button type="submit" class="btn btn-primary">Save</button>
</form>

{{ $this->modal }}
```

--------------------------------

### Set Global Max Content Width

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Globally adjust the maximum content width of the editor by setting the 'max_content_width' key in the config to a Tailwind max width size or 'full'.

```php
'max_content_width' => 'full'
```

--------------------------------

### Show Only Current Placeholder

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Control placeholder visibility to show only for the currently active node using `showOnlyCurrentPlaceholder(false)`.

```php
TiptapEditor::make('content')
    // All nodes will immediately be displayed, instead of only the selected node
    ->showOnlyCurrentPlaceholder(false)
```

--------------------------------

### Blade Preview and Rendered Views for Custom Block

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

Define the Blade views for the preview and rendered output of a custom Tiptap block. These views receive the block's form data as variables.

```blade
{{-- resources/views/blocks/previews/callout.blade.php --}}
<div class="rounded border-l-4 p-4 {{ $type === 'danger' ? 'border-red-500' : 'border-blue-500' }}">
    <p class="font-bold uppercase text-xs">{{ $type }}</p>
    <p>{{ $message }}</p>
</div>

{{-- resources/views/blocks/rendered/callout.blade.php --}}
<div class="callout callout--{{ $type }}">
    <p>{{ $message }}</p>
</div>
```

--------------------------------

### Override Modal Actions in Filament Tiptap Editor

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

Replace default modal actions for Link, Media, Grid Builder, and OEmbed with custom Filament Action classes. Ensure the custom action uses the expected default name.

```php
// config/filament-tiptap-editor.php
'link_action'         => \App\TiptapActions\CustomLinkAction::class,
'media_action'        => \App\TiptapActions\CustomMediaAction::class,
'grid_builder_action' => \App\TiptapActions\CustomGridBuilderAction::class,
'oembed_action'       => \App\TiptapActions\CustomOEmbedAction::class,
```

```php
// Custom action stub — must use the expected action name
namespace App\TiptapActions;

use Filament\Forms\Components\Actions\Action;
use Filament\Forms\Components\TextInput;

class CustomLinkAction extends Action
{
    public static function getDefaultName(): ?string
    {
        return 'filament_tiptap_link'; // required name
    }

    protected function setUp(): void
    {
        parent::setUp();

        $this->form([
            TextInput::make('href')->url()->required(),
            TextInput::make('title'),
        ]);
    }
}
```

--------------------------------

### Disable Bubble and Floating Menus

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Disable the default Bubble and Floating menus for the editor instance using `disableBubbleMenus()` and `disableFloatingMenus()`. Alternatively, these can be disabled globally in the configuration file.

```php
TiptapEditor::make('content')
    ->disableFloatingMenus()
    ->disableBubbleMenus()
```

```php
'disable_floating_menus' => true,
'disable_bubble_menus' => true,
```

--------------------------------

### Set Editor Output Format

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Specify the output format for the editor content, such as JSON. Ensure the database column is of type 'longText' or 'json' and cast appropriately in the model.

```php
use FilamentTiptapEditor\Enums\TiptapOutput;

TiptapEditor::make('content')
    ->output(FilamentTiptapEditor\TiptapOutput::Json);
```

--------------------------------

### TiptapConverter::asHTML() - HTML Rendering with Table of Contents

Source: https://context7.com/awcodes/filament-tiptap-editor/llms.txt

`asHTML()` converts content to HTML and can optionally inject anchor links into headings and generate a table of contents. The `$toc` flag enables this functionality, adding `id` attributes and `#` anchor links to headings up to a specified `$maxDepth`.

```APIDOC
## TiptapConverter::asHTML() — HTML Rendering with Table of Contents

`asHTML()` converts content to HTML and optionally injects anchor links into headings and generates a table of contents. The `$toc` flag adds `id` attributes and `#` anchor links to headings up to `$maxDepth`.

```blade
{{-- Render HTML with anchor links on headings up to h3 --}}
{!! tiptap_converter()->asHTML($post->content, toc: true, maxDepth: 3) !!}

{{-- Generate a standalone nested <ul> TOC --}}
{!! tiptap_converter()->asToc($post->content, maxDepth: 2) !!}

{{-- Generate TOC as a nested PHP array --}}
@php $headings = tiptap_converter()->asTOC($post->content, maxDepth: 3, array: true); @endphp
{{-- $headings example: [['id'=>'intro','text'=>'Intro','depth'=>2,'subs'=>[...]]] --}}

{{-- Use the built-in Blade component --}}
<x-filament-tiptap-editor::table-of-contents
    :headings="tiptap_converter()->asTOC($page->body, array: true)"
/>
```
```

--------------------------------

### Render Tiptap Content in Blade

Source: https://github.com/awcodes/filament-tiptap-editor/blob/3.x/README.md

Helper functions to convert Tiptap content (JSON) to HTML, JSON, or plain text for rendering in Blade views.

```blade
{!! tiptap_converter()->asHTML($post->content) !!}
{!! tiptap_converter()->asJSON($post->content) !!}
{!! tiptap_converter()->asText($post->content) !!}
```