Relation managers

You are currently viewing the documentation for Filament 2.x, which is a previous version of Filament.Looking for the current stable version? Visit the 5.x documentation.

Getting started

“Relation managers” in Filament allow administrators to list, create, attach, associate, edit, detach, dissociate and delete related records without leaving the resource’s Edit page. Resource classes contain a static getRelations() method that is used to register relation managers for your resource. To create a relation manager, you can use the make:filament-relation-manager command:

php artisan make:filament-relation-manager CategoryResource posts title

CategoryResource is the name of the resource class for the parent model.
posts is the name of the relationship you want to manage.
title is the name of the attribute that will be used to identify posts.

This will create a CategoryResource/RelationManagers/PostsRelationManager.php file. This contains a class where you are able to define a form and table for your relation manager:

use Filament\Forms;
use Filament\Resources\Form;
use Filament\Resources\Table;
use Filament\Tables;

public static function form(Form $form): Form
{
    return $form
        ->schema([
            Forms\Components\TextInput::make('title')->required(),
            Forms\Components\MarkdownEditor::make('content'),
            // ...
        ]);
}

public static function table(Table $table): Table
{
    return $table
        ->columns([
            Tables\Columns\TextColumn::make('title'),
            // ...
        ]);
}

You must register the new relation manager in your resource’s getRelations() method:

public static function getRelations(): array
{
    return [
        RelationManagers\PostsRelationManager::class,
    ];
}

For relationships with unconventional naming conventions, you may wish to include the $inverseRelationship property on the relation manager:

protected static ?string $inverseRelationship = 'section'; // Since the inverse related model is `Category`, this is normally `category`, not `section`.

Once a table and form have been defined for the relation manager, visit the Edit or View page of your resource to see it in action.

Handling soft deletes

By default, you will not be able to interact with deleted records in the relation manager. If you’d like to add functionality to restore, force delete and filter trashed records in your relation manager, use the --soft-deletes flag when generating the relation manager:

php artisan make:filament-relation-manager CategoryResource posts title --soft-deletes

You can find out more about soft deleting here.

Listing records

Related records will be listed in a table. The entire relation manager is based around this table, which contains actions to create, edit, attach / detach, associate / dissociate, and delete records. As per the documentation on listing records, you may use all the same utilities for customization on the relation manager:

Additionally, you may use any other feature of the table builder.

Listing with pivot attributes

For BelongsToMany and MorphToMany relationships, you may also add pivot table attributes. For example, if you have a TeamsRelationManager for your UserResource, and you want to add the role pivot attribute to the table, you can use:

use Filament\Forms;
use Filament\Resources\Form;
use Filament\Tables;

public static function table(Table $table): Table
{
    return $table
        ->columns([
            Tables\Columns\TextColumn::make('name'),
            Tables\Columns\TextColumn::make('role'),
        ]);
}

Please ensure that any pivot attributes are listed in the withPivot() method of the relationship and inverse relationship.

Creating records

Creating with pivot attributes

use Filament\Forms;
use Filament\Resources\Form;
use Filament\Tables;

public static function form(Form $form): Form
{
    return $form
        ->schema([
            Forms\Components\TextInput::make('name')->required(),
            Forms\Components\TextInput::make('role')->required(),
            // ...
        ]);
}

Please ensure that any pivot attributes are listed in the withPivot() method of the relationship and inverse relationship.

Customizing data before saving

Sometimes, you may wish to modify form data before it is finally saved to the database. To do this, you may use the mutateFormDataUsing() method, which accepts the $data as an array, and returns the modified version:

use Filament\Tables\Actions\CreateAction;

CreateAction::make()
    ->mutateFormDataUsing(function (array $data): array {
        $data['user_id'] = auth()->id();
    
        return $data;
    })

Customizing the creation process

You can tweak how the record is created using the using() method:

use Filament\Tables\Actions\CreateAction;
use Filament\Tables\Contracts\HasRelationshipTable;
use Illuminate\Database\Eloquent\Model;

CreateAction::make()
    ->using(function (HasRelationshipTable $livewire, array $data): Model {
        return $livewire->getRelationship()->create($data);
    })

Customizing the save notification

When the record is successfully created, a notification is dispatched to the user, which indicates the success of their action. To customize the text content of this notification:

use Filament\Tables\Actions\CreateAction;

CreateAction::make()
    ->successNotificationTitle('User registered')

And to disable the notification altogether:

use Filament\Tables\Actions\CreateAction;

CreateAction::make()
    ->successNotification(null)

Lifecycle hooks

Hooks may be used to execute code at various points within an action’s lifecycle.

use Filament\Tables\Actions\CreateAction;

CreateAction::make()
    ->beforeFormFilled(function () {
        // Runs before the form fields are populated with their default values.
    })
    ->afterFormFilled(function () {
        // Runs after the form fields are populated with their default values.
    })
    ->beforeFormValidated(function () {
        // Runs before the form fields are validated when the form is submitted.
    })
    ->afterFormValidated(function () {
        // Runs after the form fields are validated when the form is submitted.
    })
    ->before(function () {
        // Runs before the form fields are saved to the database.
    })
    ->after(function () {
        // Runs after the form fields are saved to the database.
    })

Halting the creation process

At any time, you may call $action->halt() from inside a lifecycle hook or mutation method, which will halt the entire creation process:

use Filament\Notifications\Actions\Action;
use Filament\Notifications\Notification;
use Filament\Resources\RelationManagers\RelationManager;
use Filament\Tables\Actions\CreateAction;

CreateAction::make()
    ->before(function (CreateAction $action, RelationManager $livewire) {
        if (! $livewire->ownerRecord->team->subscribed()) {
            Notification::make()
                ->warning()
                ->title('You don\'t have an active subscription!')
                ->body('Choose a plan to continue.')
                ->persistent()
                ->actions([
                    Action::make('subscribe')
                        ->button()
                        ->url(route('subscribe'), shouldOpenInNewTab: true),
                ])
                ->send();
        
            $action->halt();
        }
    })

If you’d like the action modal to close too, you can completely cancel() the action instead of halting it:

$action->cancel();

Editing records

Editing with pivot attributes

For BelongsToMany and MorphToMany relationships, you may also edit pivot table attributes. For example, if you have a TeamsRelationManager for your UserResource, and you want to add the role pivot attribute to the edit form, you can use:

use Filament\Forms;
use Filament\Resources\Form;
use Filament\Tables;

public static function form(Form $form): Form
{
    return $form
        ->schema([
            Forms\Components\TextInput::make('name')->required(),
            Forms\Components\TextInput::make('role')->required(),
            // ...
        ]);
}

Please ensure that any pivot attributes are listed in the withPivot() method of the relationship and inverse relationship.

Customizing data before filling the form

You may wish to modify the data from a record before it is filled into the form. To do this, you may use the mutateRecordDataUsing() method to modify the $data array, and return the modified version before it is filled into the form:

use Filament\Tables\Actions\EditAction;

EditAction::make()
    ->mutateRecordDataUsing(function (array $data): array {
        $data['user_id'] = auth()->id();
    
        return $data;
    })

Customizing data before saving

Sometimes, you may wish to modify form data before it is finally saved to the database. To do this, you may define a mutateFormDataUsing() method, which accepts the $data as an array, and returns it modified:

use Filament\Tables\Actions\EditAction;

EditAction::make()
    ->mutateFormDataUsing(function (array $data): array {
        $data['last_edited_by_id'] = auth()->id();
    
        return $data;
    })

Customizing the saving process

You can tweak how the record is updated using the using() method:

use Filament\Tables\Actions\EditAction;
use Illuminate\Database\Eloquent\Model;

EditAction::make()
    ->using(function (Model $record, array $data): Model {
        $record->update($data);

        return $record;
    })

Customizing the save notification

When the record is successfully updated, a notification is dispatched to the user, which indicates the success of their action. To customize the text content of this notification:

use Filament\Tables\Actions\EditAction;

EditAction::make()
    ->successNotificationTitle('User updated')

And to disable the notification altogether:

use Filament\Tables\Actions\EditAction;

EditAction::make()
    ->successNotification(null)

Lifecycle hooks

Hooks may be used to execute code at various points within an action’s lifecycle.

use Filament\Tables\Actions\EditAction;

EditAction::make()
    ->beforeFormFilled(function () {
        // Runs before the form fields are populated from the database.
    })
    ->afterFormFilled(function () {
        // Runs after the form fields are populated from the database.
    })
    ->beforeFormValidated(function () {
        // Runs before the form fields are validated when the form is saved.
    })
    ->afterFormValidated(function () {
        // Runs after the form fields are validated when the form is saved.
    })
    ->before(function () {
        // Runs before the form fields are saved to the database.
    })
    ->after(function () {
        // Runs after the form fields are saved to the database.
    })

Halting the saving process

At any time, you may call $action->halt() from inside a lifecycle hook or mutation method, which will halt the entire saving process:

use Filament\Notifications\Actions\Action;
use Filament\Notifications\Notification;
use Filament\Resources\RelationManagers\RelationManager;
use Filament\Tables\Actions\EditAction;

EditAction::make()
    ->before(function (EditAction $action, RelationManager $livewire) {
        if (! $livewire->ownerRecord->team->subscribed()) {
            Notification::make()
                ->warning()
                ->title('You don\'t have an active subscription!')
                ->body('Choose a plan to continue.')
                ->persistent()
                ->actions([
                    Action::make('subscribe')
                        ->button()
                        ->url(route('subscribe'), shouldOpenInNewTab: true),
                ])
                ->send();
        
            $action->halt();
        }
    })

If you’d like the action modal to close too, you can completely cancel() the action instead of halting it:

$action->cancel();

Attaching and detaching records

Filament is able to attach and detach records for BelongsToMany and MorphToMany relationships. When generating your relation manager, you may pass the --attach flag to also add AttachAction, DetachAction and DetachBulkAction to the table:

php artisan make:filament-relation-manager CategoryResource posts title --attach

Alternatively, if you’ve already generated your resource, you can just add the actions to the $table arrays:

use Filament\Resources\Table;
use Filament\Tables;

public static function table(Table $table): Table
{
    return $table
        ->columns([
            // ...
        ])
        ->headerActions([
            // ...
            Tables\Actions\AttachAction::make(),
        ])
        ->actions([
            // ...
            Tables\Actions\DetachAction::make(),
        ])
        ->bulkActions([
            // ...
            Tables\Actions\DetachBulkAction::make(),
        ]);
}

By default, as you search for a record to attach, options will load from the database via AJAX. If you wish to preload these options when the form is first loaded instead, you can use the preloadRecordSelect() method of AttachAction:

use Filament\Tables\Actions\AttachAction;

AttachAction::make()->preloadRecordSelect()

Attaching with pivot attributes

When you attach record with the Attach button, you may wish to define a custom form to add pivot attributes to the relationship:

use Filament\Forms;
use Filament\Tables\Actions\AttachAction;

AttachAction::make()
    ->form(fn (AttachAction $action): array => [
        $action->getRecordSelect(),
        Forms\Components\TextInput::make('role')->required(),
    ])

In this example, $action->getRecordSelect() outputs the select field to pick the record to attach. The role text input is then saved to the pivot table’s role column. Please ensure that any pivot attributes are listed in the withPivot() method of the relationship and inverse relationship.

Scoping the options

You may want to scope the options available to AttachAction:

use Filament\Tables\Actions\AttachAction;
use Illuminate\Database\Eloquent\Builder;

AttachAction::make()
    ->recordSelectOptionsQuery(fn (Builder $query) => $query->whereBelongsTo(auth()->user()))

Handling duplicates

By default, you will not be allowed to attach a record more than once. This is because you must also set up a primary id column on the pivot table for this feature to work. Please ensure that the id attribute is listed in the withPivot() method of the relationship and inverse relationship. Finally, add the $allowsDuplicates property to the relation manager:

protected bool $allowsDuplicates = true;

Associating and dissociating records

Filament is able to associate and dissociate records for HasMany and MorphMany relationships. When generating your relation manager, you may pass the --associate flag to also add AssociateAction, DissociateAction and DissociateBulkAction to the table:

php artisan make:filament-relation-manager CategoryResource posts title --associate

Alternatively, if you’ve already generated your resource, you can just add the actions to the $table arrays:

use Filament\Resources\Table;
use Filament\Tables;

public static function table(Table $table): Table
{
    return $table
        ->columns([
            // ...
        ])
        ->headerActions([
            // ...
            Tables\Actions\AssociateAction::make(),
        ])
        ->actions([
            // ...
            Tables\Actions\DissociateAction::make(),
        ])
        ->bulkActions([
            // ...
            Tables\Actions\DissociateBulkAction::make(),
        ]);
}

By default, as you search for a record to associate, options will load from the database via AJAX. If you wish to preload these options when the form is first loaded instead, you can use the preloadRecordSelect() method of AssociateAction:

use Filament\Tables\Actions\AssociateAction;

AssociateAction::make()->preloadRecordSelect()

Scoping the options

You may want to scope the options available to AssociateAction:

use Filament\Tables\Actions\AssociateAction;
use Illuminate\Database\Eloquent\Builder;

AssociateAction::make()
    ->recordSelectOptionsQuery(fn (Builder $query) => $query->whereBelongsTo(auth()->user())

Viewing records

When generating your relation manager, you may pass the --view flag to also add a ViewAction to the table:

php artisan make:filament-relation-manager CategoryResource posts title --view

Alternatively, if you’ve already generated your relation manager, you can just add the ViewAction to the $table->actions() array:

use Filament\Resources\Table;
use Filament\Tables;

public static function table(Table $table): Table
{
    return $table
        ->columns([
            // ...
        ])
        ->actions([
            Tables\Actions\ViewAction::make(),
            // ...
        ]);
}

Deleting records

php artisan make:filament-relation-manager CategoryResource posts title --soft-deletes

Alternatively, you may add soft deleting functionality to an existing relation manager:

use Filament\Resources\Table;
use Filament\Tables;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\SoftDeletingScope;

public static function table(Table $table): Table
{
    return $table
        ->columns([
            // ...
        ])
        ->filters([
            Tables\Filters\TrashedFilter::make(),
            // ...
        ])
        ->actions([
            Tables\Actions\DeleteAction::make(),
            Tables\Actions\ForceDeleteAction::make(),
            Tables\Actions\RestoreAction::make(),
            // ...
        ])
        ->bulkActions([
            Tables\Actions\DeleteBulkAction::make(),
            Tables\Actions\ForceDeleteBulkAction::make(),
            Tables\Actions\RestoreBulkAction::make(),
            // ...
        ]);
}

protected function getTableQuery(): Builder
{
    return parent::getTableQuery()
        ->withoutGlobalScopes([
            SoftDeletingScope::class,
        ]);
}

Lifecycle hooks

You can use the before() and after() methods to execute code before and after a record is deleted:

use Filament\Tables\Actions\DeleteAction;

DeleteAction::make()
    ->before(function () {
        // ...
    })
    ->after(function () {
        // ...
    })

Halting the deletion process

At any time, you may call $action->halt() from inside a lifecycle hook or mutation method, which will halt the entire deletion process:

use Filament\Notifications\Actions\Action;
use Filament\Notifications\Notification;
use Filament\Resources\RelationManagers\RelationManager;
use Filament\Tables\Actions\DeleteAction;

DeleteAction::make()
    ->before(function (DeleteAction $action, RelationManager $livewire) {
        if (! $livewire->ownerRecord->team->subscribed()) {
            Notification::make()
                ->warning()
                ->title('You don\'t have an active subscription!')
                ->body('Choose a plan to continue.')
                ->persistent()
                ->actions([
                    Action::make('subscribe')
                        ->button()
                        ->url(route('subscribe'), shouldOpenInNewTab: true),
                ])
                ->send();
        
            $action->halt();
        }
    })

If you’d like the action modal to close too, you can completely cancel() the action instead of halting it:

$action->cancel();

Accessing the owner record

Relation managers are Livewire components. When they are first loaded, the owner record (the Eloquent record which serves as a parent - the main resource model) is mounted in a public $ownerRecord property. Thus, you may access the owner record using:

$this->ownerRecord

However, in you’re inside a static method like form() or table(), $this isn’t accessible. So, you may use a callback to access the $livewire instance:

use Filament\Forms;
use Filament\Resources\Form;
use Filament\Resources\RelationManagers\RelationManager;

public static function form(Form $form): Form
{
    return $form
        ->schema([
            Forms\Components\Select::make('store_id')
                ->options(function (RelationManager $livewire): array {
                    return $livewire->ownerRecord->stores()
                        ->pluck('name', 'id')
                        ->toArray();
                }),
            // ...
        ]);
}

All methods in Filament accept a callback which you can access $livewire->ownerRecord in.

Grouping relation managers

You may choose to group relation managers together into one tab. To do this, you may wrap multiple managers in a RelationGroup object, with a label:

use Filament\Resources\RelationManagers\RelationGroup;

public static function getRelations(): array
{
    return [
        // ...
        RelationGroup::make('Contacts', [
            RelationManagers\IndividualsRelationManager::class,
            RelationManagers\OrganizationsRelationManager::class,
        ]),
        // ...
    ];
}

Conditional visibility

By default, relation managers will be visible if the viewAny() method for the related model policy returns true. You may use the canViewForRecord() method to determine if the relation manager should be visible for a specific owner record:

use Illuminate\Database\Eloquent\Model;

public static function canViewForRecord(Model $ownerRecord): bool
{
    return $ownerRecord->status === Status::Draft;
}

Moving the resource form to tabs

On the Edit or View page class, override the hasCombinedRelationManagerTabsWithForm() method:

public function hasCombinedRelationManagerTabsWithForm(): bool
{
    return true;
}

​Getting started

​Handling soft deletes

​Listing records

​Listing with pivot attributes

​Creating records

​Creating with pivot attributes

​Customizing data before saving

​Customizing the creation process

​Customizing the save notification

​Lifecycle hooks

​Halting the creation process

​Editing records

​Editing with pivot attributes

​Customizing data before filling the form

​Customizing data before saving

​Customizing the saving process

​Customizing the save notification

​Lifecycle hooks

​Halting the saving process

​Attaching and detaching records

​Preloading the attachment modal select options

​Attaching with pivot attributes

​Scoping the options

​Handling duplicates

​Associating and dissociating records

​Preloading the associate modal select options

​Scoping the options

​Viewing records

​Deleting records

​Lifecycle hooks

​Halting the deletion process

​Accessing the owner record

​Grouping relation managers

​Conditional visibility

​Moving the resource form to tabs

Getting started

Handling soft deletes

Listing records

Listing with pivot attributes

Creating records

Creating with pivot attributes

Customizing data before saving

Customizing the creation process

Customizing the save notification

Lifecycle hooks

Halting the creation process

Editing records

Editing with pivot attributes

Customizing data before filling the form

Customizing data before saving

Customizing the saving process

Customizing the save notification

Lifecycle hooks

Halting the saving process

Attaching and detaching records

Preloading the attachment modal select options

Attaching with pivot attributes

Scoping the options

Handling duplicates

Associating and dissociating records

Preloading the associate modal select options

Scoping the options

Viewing records

Deleting records

Lifecycle hooks

Halting the deletion process

Accessing the owner record

Grouping relation managers

Conditional visibility

Moving the resource form to tabs