filamentphp/filament: Document Livewire nesting depth configuration for rich editor

Filament's rich editor keeps its TipTap document in sync with Livewire by transmitting the content as deeply nested data. Livewire limits nested property paths to 10 levels by default, and rich content with nested lists, tables or grids can easily exceed that, failing with Livewire\Exceptions\MaxNestingDepthExceededException. Pull request #20421 is a documentation-only change that addresses this: it adds a new section to the rich editor documentation, "Configuring Livewire's maximum nesting depth", which explains how to publish Livewire's configuration file and raise the max_nesting_depth setting. There are no visual changes, no functional changes and no code changes at all, so upgrading from v4.15.1 carries no behavioral risk — but if you have run into this exception, the fix is now officially documented. This resolves issue #20393.

What changed

A single documentation file was touched: packages/forms/docs/10-rich-editor.md. The new section covers three things:

1. Why the exception happens — the rich editor synchronizes its TipTap document with Livewire as nested data, and Livewire caps nested property paths at 10 levels by default, which nested lists and tables can outgrow.
2. How to publish Livewire's config when your application doesn't already have one, using php artisan livewire:publish --config — including a warning that this command overwrites an existing config/livewire.php, so you should skip it if you have already published the file.
3. How to increase the limit by editing the max_nesting_depth value inside the payload array — and, just as importantly, changing only that value so you preserve Livewire's other version-specific payload settings.

Prettier and git diff --check pass, and the documentation checkbox is ticked. Nothing in the runtime code was modified.

Why it matters

The default nesting limit is a Livewire-level guard, not a Filament bug, but it surfaces through Filament's rich editor. The editor's document model is a tree: a bullet list inside a table cell inside another list, and so on. Every level of nesting in the content maps to another level in the JSON payload Livewire manages. Content authors don't think in terms of property paths, so hitting "max nesting depth exceeded" while editing an innocent-looking nested list is deeply confusing. Until now, the remedy — bumping a single config value — was only discoverable by reading Livewire's source or asking on GitHub. Documenting the relationship between the rich editor and this setting turns a dead end into a two-minute fix and gives support channels a canonical answer to link to.

How to apply the configuration

If any RichEditor::make('content') field in your app throws the exception, first check whether config/livewire.php exists. If it doesn't, publish it:

php artisan livewire:publish --config

Be careful here: re-running this command overwrites any existing config/livewire.php, so skip it entirely if you have already published and customized the file.

Then increase the existing setting. The docs suggest a depth of 32, which leaves generous room for deeply nested rich content:

// config/livewire.php
'payload' => [
    // ...
    'max_nesting_depth' => 32,
],

If you already published Livewire's configuration previously, don't re-publish — just edit the existing payload.max_nesting_depth value instead. And resist the urge to flatten or restructure the payload array; it holds other version-specific settings that Livewire relies on.

Upgrade impact

• None, functionally. This PR ships documentation only; no Filament classes, config, JavaScript or CSS changed, so upgrading from v4.15.1 introduces no new behavior and no deprecations.
• If you have never seen MaxNestingDepthExceededException, there is nothing to do.
• If you already raised max_nesting_depth on your own after hitting issue #20393, your setup should already match the documented approach — it's worth double-checking that your value sits inside the payload array rather than at the top level of the config file.
• If you were previously afraid to publish config/livewire.php for fear of losing tweaks, the docs now explicitly warn about the overwrite behavior.

Takeaways

• PR #20421 documents the fix for Livewire\Exceptions\MaxNestingDepthExceededException when saving rich editor content.
• Publish Livewire's config with php artisan livewire:publish --config, but skip the command if config/livewire.php already exists — it overwrites the file.
• Increase payload.max_nesting_depth (for example to 32) in config/livewire.php, changing only that one value.
• Documentation-only change: safe to upgrade from v4.15.1 with zero code or behavior impact.

Category: Documentation (6)

Sources

• Pull request #20421
• Release v5.10.1