README

Overview

Filament Master Detail is a dynamic management plugin for HasMany (1,n) relationships in FilamentPHP. It allows you to add and remove related records directly within the parent form, without the need to save the parent record first. Ideal for fast and fluid data entry scenarios.

Table of Contents

• Installation
• Basic Usage
• Common Use Cases
• Additional Features
  • Modal Behavior & Customization
    • Slideover Mode
    • Set Custom Labels
    • Set Modal Icon and Width
    • Keep Modal Open After Adding
    • Customize Table Heading
    • Preserve Field Values
    • Manipulate Data Before Adding
    • Add Header Actions
• Full Example
• FAQ
• Screenshots
  • Table View
  • Add New Item
  • Remove Item
  • Slideover Mode
  • Video Demo
• Changelog
• Contributing
• Security
• License

Installation

Requirements

• PHP >= 8.1
• Laravel >= 10
• Filament >= 3.x

Installation Steps

  composer require rodrigofs/filament-masterdetail

Basic Usage

Important: When using the table(...) method, it is not compatible with Filament's TextColumn or other default columns. You must exclusively use the DataColumn provided by this package.

Example

use Rodrigofs\FilamentMasterDetail\Forms\Components\MasterDetail;
use Rodrigofs\FilamentMasterDetail\Tables\Columns\DataColumn;

MasterDetail::make('items')
    ->relationship('items')
    ->schema([
        TextInput::make('name')->required(),
        TextInput::make('description'),
    ])
    ->table([
        DataColumn::make('name'),
        DataColumn::make('description'),
    ]);

Define the HasMany relationship in the parent model:

public function items(): HasMany
{
    return $this->hasMany(Item::class);
}

Common Use Cases

Order Creation with Items

use Rodrigofs\FilamentMasterDetail\Forms\Components\MasterDetail;
use Rodrigofs\FilamentMasterDetail\Tables\Columns\DataColumn;

MasterDetail::make('items')
    ->relationship()
    ->schema([
        Select::make('shop_product_id')
            ->label('Product')
            ->options(Product::query()->pluck('name', 'id'))
            ->required()
            ->reactive()
            ->afterStateUpdated(fn ($state, Set $set) => $set('price', Product::find($state)?->price ?? 0))
            ->distinct()
            ->disableOptionsWhenSelectedInSiblingRepeaterItems()
            ->columnSpan(['md' => 5])
            ->searchable(),

        TextInput::make('quantity')
            ->label('Quantity')
            ->numeric()
            ->default(1)
            ->required()
            ->columnSpan(['md' => 2]),

        TextInput::make('price')
            ->label('Unit Price')
            ->numeric()
            ->disabled()
            ->dehydrated()
            ->required()
            ->columnSpan(['md' => 3]),
    ])
    ->unique('shop_product_id')
    ->table([
        DataColumn::make('product.name')
            ->label('Product')
            ->columnWidth('w-1/3'),

        DataColumn::make('quantity')
            ->label('Quantity')
            ->columnWidth('w-1/3'),

        DataColumn::make('price')
            ->label('Unit Price')
            ->columnWidth('w-1/3'),

        DataColumn::make('total')
            ->formatStateUsing(fn ($rowLoop) => $rowLoop->price * $rowLoop->quantity)
            ->label('Total')
            ->columnWidth('w-1/3'),
    ]);

Additional Features

Modal Behavior & Customization

You can customize the behavior and appearance of the modal used to add related records:

Slideover Mode

Display the form inside a Slideover instead of a traditional modal:

use Rodrigofs\FilamentMasterDetail\Components\MasterDetail;

MasterDetail::make('items')
    ->slideover()
    ->schema([
        // Form fields
    ]);

Set Custom Labels

Define the labels for modal actions and headings:

use Rodrigofs\FilamentMasterDetail\Forms\Components\MasterDetail;

MasterDetail::make('items')
    ->addActionLabel('Add Product')
    ->modalHeading('Add Product')
    ->modalDescription('Include a new product in this order.')
    ->modalSubmitActionLabel('Add')
    ->modalCancelActionLabel('Cancel');

Set Modal Icon and Width

Customize the modal icon and size:

use Rodrigofs\FilamentMasterDetail\Forms\Components\MasterDetail;

MasterDetail::make('items')
    ->modalIcon('heroicon-o-plus')
    ->modalWidth('lg');

Keep Modal Open After Adding

Prevent the modal from closing automatically after adding a record:

use Rodrigofs\FilamentMasterDetail\Forms\Components\MasterDetail;

MasterDetail::make('items')
    ->modalPersistent();

Customize Table Heading

Set a custom heading for the related records table:

use Rodrigofs\FilamentMasterDetail\Forms\Components\MasterDetail;

MasterDetail::make('items')
    ->heading('Order Items');

Preserve Field Values

Prevent specific fields from being cleared after adding a record:

use Rodrigofs\FilamentMasterDetail\Forms\Components\MasterDetail;

MasterDetail::make('items')
    ->formExceptClear(['product_id']);

Manipulate Data Before Adding

Allow data manipulation before the record is added to the table:

use Rodrigofs\FilamentMasterDetail\Forms\Components\MasterDetail;

MasterDetail::make('items')
    ->beforeAddActionExecute(fn ($state, $set) => $set('product_id', $state));

Add Header Actions

Define custom actions in the header of the MasterDetail component:

use Rodrigofs\FilamentMasterDetail\Forms\Components\MasterDetail;

MasterDetail::make('items')
    ->headerActions([
        Action::make('clear')
            ->label('Clear Items')
            ->action(fn ($component) => $component->clear())
            ->requiresConfirmation(),
    ]);

Full Example

use Rodrigofs\FilamentMasterDetail\Forms\Components\MasterDetail;

MasterDetail::make('items')
    ->relationship()
    ->schema([
        Select::make('product_id')
            ->label('Product')
            ->options(Product::query()->pluck('name', 'id'))
            ->required(),
        TextInput::make('quantity')
            ->numeric()
            ->required(),
    ])
    ->addActionLabel('Add Product')
    ->modalHeading('Add Product')
    ->modalDescription('Include a new product in this order.')
    ->modalIcon('heroicon-o-plus')
    ->modalWidth('lg')
    ->modalSubmitActionLabel('Add')
    ->modalCancelActionLabel('Cancel')
    ->heading('Order Items')
    ->formExceptClear(['product_id'])
    ->beforeAddActionExecute(fn ($state, $set) => $set('product_id', $state))
    ->headerActions([
        Action::make('clear')
            ->label('Clear Items')
            ->action(fn ($component) => $component->clear())
            ->requiresConfirmation(),
    ])
    ->slideOver();

FAQ

1. Do I need to save the parent record before adding related records? No. MasterDetail allows adding and removing related records before persisting the parent model.

2. Does it support other relationship types besides HasMany? Currently, only HasMany relationships are supported.

3. Is there support for editing related records? No. Only adding and removing records is supported at the moment.

Screenshots

Table View

Add New Item in Modal

Remove Item with Confirmation

Slideover Mode

Video Demo

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Rodrigo Fernandes
• All Contributors

License

The MIT License (MIT). Please see License File for more information.