Filament v3 → v4 Migration: Breaking Changes | Mohamed Said [Skip to content](#main) [ ![](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed SaidLaravel Backend Engineer ](https://www.msaied.com/public) - [Home](https://www.msaied.com/public) - [Projects](https://www.msaied.com/public/projects) - [Articles](https://www.msaied.com/public/articles) - [Certificates](https://www.msaied.com/public/certificates) - [About](https://www.msaied.com/public#about) [ Contact](https://www.msaied.com/public#contact) Menu Menu ---- Close - [HomeStart here](https://www.msaied.com/public) - [ProjectsCase studies](https://www.msaied.com/public/projects) - [ArticlesEngineering notes](https://www.msaied.com/public/articles) - [CertificatesCredentials](https://www.msaied.com/public/certificates) - [AboutHow I work](https://www.msaied.com/public#about) - [ContactGet in touch](https://www.msaied.com/public#contact) [Start a conversation](https://www.msaied.com/public#contact) [WhatsApp](https://wa.me/201094619204) [Email](mailto:hello@msaied.com) 1. [Home](https://www.msaied.com/public) 2. / 3. [Articles](https://www.msaied.com/public/articles) 4. / 5. Filament v3 to v4 Migration: Breaking Changes and Practical Refactor Patterns Filament v3 to v4 Migration: Breaking Changes and Practical Refactor Patterns ============================================================================== Filament v4 rewrites form and infolist rendering around a unified Schema API. This guide covers the real breaking changes, the refactor patterns that matter, and the traps that will cost you hours if you miss them. ![](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) [Mohamed Said](https://www.msaied.com/public#person) Published 29 Jun 2026 · Updated 29 Jun 2026 · 4 min read ShareCopy linkCopied ![Filament v3 to v4 Migration: Breaking Changes and Practical Refactor Patterns](https://cdn.msaied.com/324/01abd51e9d76dcd7d126a4e77e2074f6.png) On this page +1. [Why v4 Is Not a Cosmetic Upgrade](#why-v4-is-not-a-cosmetic-upgrade) 2. [Breaking Change 1 — Schema Replaces Parallel Component Trees](#breaking-change-1-schema-replaces-parallel-component-trees) 3. [Breaking Change 2 — Action mountUsing and fillForm Signatures](#breaking-change-2-action-codemountusingcode-and-codefillformcode-signatures) 4. [Breaking Change 3 — Removed ->columns() Shorthand on Groups](#breaking-change-3-removed-code-gtcolumnscode-shorthand-on-groups) 5. [Refactor Pattern: Extract a Shared Schema Method](#refactor-pattern-extract-a-shared-schema-method) 6. [Updating Pest Tests](#updating-pest-tests) 7. [Takeaways](#takeaways) Why v4 Is Not a Cosmetic Upgrade -------------------------------- Filament v4 ships a unified `Schema` API that replaces the parallel `Form` / `Infolist` component trees from v3. If you have large resources with custom fields, repeated `make()` factories, or inline closures scattered across `form()` and `infolist()` methods, you will touch almost every resource file. The good news: the migration is mechanical once you understand the three core shifts. --- Breaking Change 1 — Schema Replaces Parallel Component Trees ------------------------------------------------------------ In v3 you maintained two separate component hierarchies: ```php // v3 public static function form(Form $form): Form { return $form->schema([ TextInput::make('name')->required(), ]); } public static function infolist(Infolist $infolist): Infolist { return $infolist->schema([ TextEntry::make('name'), ]); } ``` In v4 both methods receive a `Schema` object and share the same component namespace when you opt into the unified path: ```php // v4 use Filament\Schema\Schema; public static function form(Schema $schema): Schema { return $schema->components([ TextInput::make('name')->required(), ]); } public static function infolist(Schema $schema): Schema { return $schema->components([ TextEntry::make('name'), ]); } ``` The `->schema()` method still works as an alias during the transition period, but relying on it will generate deprecation notices and will be removed in a future minor. --- Breaking Change 2 — Action `mountUsing` and `fillForm` Signatures ----------------------------------------------------------------- v3 actions used `mountUsing` to pre-fill a modal form: ```php // v3 Action::make('approve') ->mountUsing(fn (ComponentContainer $form, Model $record) => $form->fill(['note' => $record->last_note]) ) ``` v4 replaces `ComponentContainer` with `Schema` and renames the hook: ```php // v4 use Filament\Schema\Schema; Action::make('approve') ->fillForm(fn (Model $record): array => [ 'note' => $record->last_note, ]) ->form([ Textarea::make('note')->required(), ]) ``` `mountUsing` is removed entirely. Any resource or page that injects `ComponentContainer` will throw a class-not-found error at runtime — grep your codebase before upgrading. --- Breaking Change 3 — Removed `->columns()` Shorthand on Groups ------------------------------------------------------------- v3 allowed `Grid::make()->columns(2)` as a fluent shorthand. v4 enforces `Grid::make(2)` as the canonical constructor argument: ```php // v3 — still parses but deprecated Grid::make()->columns(2) // v4 — correct Grid::make(2)->schema([...]) ``` This is a silent runtime regression in v3 compatibility mode: the grid renders as a single column without an error. Add a search for `->columns(` on `Grid` instances to your pre-upgrade checklist. --- Refactor Pattern: Extract a Shared Schema Method ------------------------------------------------ When form and infolist share 80 % of their fields, extract a private static method rather than duplicating: ```php private static function coreFields(bool $readonly = false): array { return [ TextInput::make('name') ->required() ->disabled($readonly), DatePicker::make('published_at') ->disabled($readonly), ]; } public static function form(Schema $schema): Schema { return $schema->components(static::coreFields()); } public static function infolist(Schema $schema): Schema { return $schema->components(static::coreFields(readonly: true)); } ``` This pattern eliminates drift between the two views and makes future field additions a single-line change. --- Updating Pest Tests ------------------- Filament's test helpers mirror the API changes. The `assertFormFieldExists` and `assertInfolists` assertions now accept a `Schema` context: ```php it('renders the name field in the form', function () { livewire(EditPost::class, ['record' => Post::factory()->create()]) ->assertFormFieldExists('name') ->assertFormFieldIsRequired('name'); }); ``` No change needed here — the helpers are backward-compatible. What does break is any test that directly instantiates `ComponentContainer`: ```php // Remove this pattern entirely $container = ComponentContainer::make($livewire)->statePath('data'); ``` Replace with the Livewire component test helpers; they handle schema resolution internally. --- Takeaways --------- - Grep for `ComponentContainer`, `mountUsing`, and `->columns(` on `Grid` before touching anything else. - The `Schema` type hint is the single biggest mechanical change — a project-wide find-and-replace handles 90 % of it. - Extract shared field arrays into private static methods to avoid form/infolist drift. - `fillForm(fn)` replaces `mountUsing` for action pre-population; the old hook is gone, not deprecated. - Pest test helpers are largely compatible; only direct `ComponentContainer` instantiation breaks. - [filament](https://www.msaied.com/public/articles?search=filament) - [laravel](https://www.msaied.com/public/articles?search=laravel) - [upgrade](https://www.msaied.com/public/articles?search=upgrade) - [filament-v4](https://www.msaied.com/public/articles?search=filament-v4) Frequently asked questions --------------------------- Can I upgrade a large Filament v3 app to v4 incrementally?Filament v4 ships a compatibility layer that keeps `->schema()` as an alias and tolerates some v3 patterns, but `ComponentContainer` and `mountUsing` are hard-removed. You must fix those before the app boots. Everything else can be migrated resource by resource. Do custom Filament v3 field plugins need to be rewritten for v4?Plugins that extend `Field` and only override `getView()` or `setUp()` typically need only a type-hint update from `ComponentContainer` to `Schema`. Plugins that hook into the component tree lifecycle more deeply will need targeted refactoring around the new Schema render pipeline. Will Filament v3 receive security patches after v4 is stable?The Filament team has historically maintained the previous major for critical security fixes for a limited window after a new major ships. Check the official GitHub releases page for the current support policy rather than relying on community estimates. ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp)About the author ---------------- [Mohamed Said](https://www.msaied.com/public#person)Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. [About](https://www.msaied.com/public#about) [GitHub ↗](https://github.com/EG-Mohamed) [LinkedIn ↗](https://www.linkedin.com/in/msaiedm/) [WhatsApp ↗](https://wa.me/201094619204) [Email Address ↗](mailto:hello@msaied.com) [My CV ↗](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view) [Previous articleYour Symfony App Now Runs on Laravel Cloud](https://www.msaied.com/public/articles/your-symfony-app-now-runs-on-laravel-cloud) [Next articleProduction AI Agents in Laravel: Streaming, Token Budgets, and Structured Output Contracts](https://www.msaied.com/public/articles/production-ai-agents-in-laravel-streaming-token-budgets-and-structured-output-contracts-1) On this page ------------- 1. [Why v4 Is Not a Cosmetic Upgrade](#why-v4-is-not-a-cosmetic-upgrade) 2. [Breaking Change 1 — Schema Replaces Parallel Component Trees](#breaking-change-1-schema-replaces-parallel-component-trees) 3. [Breaking Change 2 — Action mountUsing and fillForm Signatures](#breaking-change-2-action-codemountusingcode-and-codefillformcode-signatures) 4. [Breaking Change 3 — Removed ->columns() Shorthand on Groups](#breaking-change-3-removed-code-gtcolumnscode-shorthand-on-groups) 5. [Refactor Pattern: Extract a Shared Schema Method](#refactor-pattern-extract-a-shared-schema-method) 6. [Updating Pest Tests](#updating-pest-tests) 7. [Takeaways](#takeaways) ### Have a technical challenge? Tell me what you’re building. I reply within two working days. [Start a conversation](https://www.msaied.com/public#contact) Related articles ----------------- [ ![](https://cdn.msaied.com/740/cce86edc21eddcbdd2f2454fadaf9c70.png) · 3 min read### The Pipeline Pattern in Laravel: Custom Pipelines Beyond Middleware 5 Oct 2026 ](https://www.msaied.com/public/articles/the-pipeline-pattern-in-laravel-custom-pipelines-beyond-middleware-1) [ ![](https://cdn.msaied.com/739/2d6897fdcdcf090613f96f72a64b8a78.png) · 4 min read### MySQL Full-Text Search in Laravel: Indexes, Relevance Scoring, and Boolean Mode 4 Oct 2026 ](https://www.msaied.com/public/articles/mysql-full-text-search-in-laravel-indexes-relevance-scoring-and-boolean-mode) [ ![](https://cdn.msaied.com/738/073696a3fefe18bec825beec5ac658f5.png) · 4 min read### Laravel Queue Rate-Limited Middleware: Throttling Jobs Without Losing Work 4 Oct 2026 ](https://www.msaied.com/public/articles/laravel-queue-rate-limited-middleware-throttling-jobs-without-losing-work) Have a technical challenge? ---------------------------- Tell me what you’re building. I reply within two working days. [Discuss your project ↗](https://www.msaied.com/public#contact) © 2026 Mohamed Said · Built with Laravel, meant to last.Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. - [Home](https://www.msaied.com/public) - [Articles](https://www.msaied.com/public/articles) - [Certificates](https://www.msaied.com/public/certificates) - [GitHub](https://github.com/EG-Mohamed) - [LinkedIn](https://www.linkedin.com/in/msaiedm/) - [WhatsApp](https://wa.me/201094619204) - [Email Address](mailto:hello@msaied.com) - [My CV](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view) - [Sitemap](https://www.msaied.com/public/sitemap.xml)