Filament v3 → v4 Migration: Breaking Changes | Mohamed Said [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://msaied.com) [ Home ](https://msaied.com) [ Projects ](https://msaied.com/projects) [ Articles ](https://msaied.com/articles) [ Certificates ](https://msaied.com/certificates) [ Contact ](https://msaied.com#contact-section) [ ](https://github.com/EG-Mohamed) [ Home ](https://msaied.com) [ Projects ](https://msaied.com/projects) [ Articles ](https://msaied.com/articles) [ Certificates ](https://msaied.com/certificates) [ Contact ](https://msaied.com#contact-section) [ home ](https://msaied.com) [ articles ](https://msaied.com/articles) Filament v3 to v4 Migration: Breaking Changes and Practical Refactor Patterns 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) ![Filament v3 to v4 Migration: Breaking Changes and Practical Refactor Patterns](https://cdn.msaied.com/324/01abd51e9d76dcd7d126a4e77e2074f6.png) #filament #laravel #upgrade #filament-v4 Filament v3 to v4 Migration: Breaking Changes and Practical Refactor Patterns =============================================================================== 29 Jun 2026 4 min read ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said Table of contents 1. [ 01 Why v4 Is Not a Cosmetic Upgrade ](#why-v4-is-not-a-cosmetic-upgrade) 2. [ 02 Breaking Change 1 — Schema Replaces Parallel Component Trees ](#breaking-change-1-schema-replaces-parallel-component-trees) 3. [ 03 Breaking Change 2 — Action mountUsing and fillForm Signatures ](#breaking-change-2-action-codemountusingcode-and-codefillformcode-signatures) 4. [ 04 Breaking Change 3 — Removed ->columns() Shorthand on Groups ](#breaking-change-3-removed-code-gtcolumnscode-shorthand-on-groups) 5. [ 05 Refactor Pattern: Extract a Shared Schema Method ](#refactor-pattern-extract-a-shared-schema-method) 6. [ 06 Updating Pest Tests ](#updating-pest-tests) 7. [ 07 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. Found this useful? [ ](https://twitter.com/intent/tweet?url=https%3A%2F%2Fmsaied.com%2Farticles%2Ffilament-v3-to-v4-migration-breaking-changes-and-practical-refactor-patterns-1&text=Filament+v3+to+v4+Migration%3A+Breaking+Changes+and+Practical+Refactor+Patterns) [ ](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fmsaied.com%2Farticles%2Ffilament-v3-to-v4-migration-breaking-changes-and-practical-refactor-patterns-1) Frequently Asked Questions ---------------------------- 3 questions Q01 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. Q02 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. Q03 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. Continue reading More Articles --------------- [ View all ](https://msaied.com/articles) [ ![Laravel 13: New Features, Helpers, and Practical Upgrade Notes](https://cdn.msaied.com/339/58c4fa6fe9b6d25a2dac17c621b6f4c6.png) laravel laravel-13 upgrade ### Laravel 13: New Features, Helpers, and Practical Upgrade Notes Laravel 13 ships with async-first defaults, a leaner bootstrapping layer, and several quality-of-life helpers.... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 1 Jul 2026 3 min read Read ](https://msaied.com/articles/laravel-13-new-features-helpers-and-practical-upgrade-notes) [ ![Laravel 12: Structured Route Files, Slim Skeletons, and the New Application Bootstrapping](https://cdn.msaied.com/337/05b39d16d0f88a5fb94d0cf74049b88b.png) laravel laravel-12 upgrade ### Laravel 12: Structured Route Files, Slim Skeletons, and the New Application Bootstrapping Laravel 12 ships with a leaner skeleton, first-class route file organisation, and a revised application bootst... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 1 Jul 2026 3 min read Read ](https://msaied.com/articles/laravel-12-structured-route-files-slim-skeletons-and-the-new-application-bootstrapping) [ ![Laravel API Resources: Sparse Fieldsets, Conditional Relationships, and Versioning](https://cdn.msaied.com/336/89d518450335e8fcdaa5be882cf4dd3e.png) laravel api resources ### Laravel API Resources: Sparse Fieldsets, Conditional Relationships, and Versioning Go beyond basic API resources. Learn how to implement sparse fieldsets, conditionally load relationships, and... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 1 Jul 2026 3 min read Read ](https://msaied.com/articles/laravel-api-resources-sparse-fieldsets-conditional-relationships-and-versioning) [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://msaied.com)Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. Explore - [Home](https://msaied.com) - [Projects](https://msaied.com/projects) - [Articles](https://msaied.com/articles) - [Certificates](https://msaied.com/certificates) - [Contact](https://msaied.com#contact-section) Connect - [ hello@msaied.com ](mailto:hello@msaied.com) - [ +20 109 461 9204 ](tel:+201094619204) © 2026 Mohamed Said. All rights reserved. [ ](https://github.com/EG-Mohamed) [ ](https://www.linkedin.com/in/msaiedm/) [ ](https://wa.me/201094619204) [ ](mailto:hello@msaied.com) [ ](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view)