README

Important

Please note that we will only be updating to version 3.x, excluding any bug fixes.

Filament Tree

Filament Tree is a plugin for Filament Admin that creates hierarchical tree management with drag-and-drop functionality. Perfect for building menus, categories, organizational structures, and any nested data relationships.

🎯 Key Features:

Drag-and-drop tree interface with unlimited depth
Support for Widgets, Pages, and Resources
Customizable actions, icons, and styling
Translation support with Spatie Translatable
Built-in create, edit, delete, and view actions
Toolbar actions for global operations

🚀 Demo: https://filament-cms-website-demo.solutionforest.net/admin
Credentials: demo@solutionforest.net / 12345678 (Auto-reset every hour)

Version Compatibility

Filament Version	Plugin Version
v3	2.x.x
v4	3.x.x

Important

We only provide updates for versions 3.x, excluding bug fixes for older versions.

Installation

Install the package:

composer require solution-forest/filament-tree

Publish and register assets:
```
php artisan filament:assets
```

Publish configuration (optional):

php artisan vendor:publish --tag="filament-tree-config"

For custom themes: Add to your tailwind.config.js:

@import '<path-to-vendor>/solution-forest/filament-tree/resources/css/jquery.nestable.css';
@import '<path-to-vendor>/solution-forest/filament-tree/resources/css/button.css';
@import '<path-to-vendor>/solution-forest/filament-tree/resources/css/custom-nestable-item.css';
@source '<path-to-vendor>/solution-forest/filament-tree/resources/**/*.blade.php';

Quick Start

1. Database Setup

Create your migration with the required tree structure:

Schema::create('categories', function (Blueprint $table) {
    $table->id();
    $table->treeColumns(); // Adds parent_id, order, title columns
    $table->timestamps();
});

// Or manually:
Schema::create('categories', function (Blueprint $table) {
    $table->id();
    $table->integer('parent_id')->default(-1)->index(); // Must default to -1!
    $table->integer('order')->default(0);
    $table->string('title');
    $table->timestamps();
});

2. Model Setup

Add the ModelTree trait to your Eloquent model:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use SolutionForest\FilamentTree\Concern\ModelTree;

class Category extends Model
{
    use ModelTree;

    protected $fillable = ['parent_id', 'title', 'order'];

    protected $casts = [
        'parent_id' => 'integer'
    ];
}

3. Generate Tree Components

Choose your implementation:

# For a standalone tree widget
php artisan make:filament-tree-widget CategoryWidget --model=Category

# For a tree page
php artisan make:filament-tree-page CategoryTree --model=Category

# For a resource tree page
php artisan make:filament-tree-page CategoryTree --resource=Category

Implementation Options

Tree Widgets

Perfect for embedding trees within existing resource pages or dashboard.

1. Generate the widget:

php artisan make:filament-tree-widget CategoryWidget --model=Category

2. Configure the widget:

<?php

namespace App\Filament\Widgets;

use App\Models\Category;
use Filament\Forms\Components\TextInput;
use SolutionForest\FilamentTree\Widgets\Tree as BaseWidget;

class CategoryWidget extends BaseWidget
{
    protected static string $model = Category::class;
    protected static int $maxDepth = 3;
    protected ?string $treeTitle = 'Categories';
    protected bool $enableTreeTitle = true;

    protected function getFormSchema(): array
    {
        return [
            TextInput::make('title')->required(),
            // Add more form fields as needed
        ];
    }
}

3. Display in resource pages:

// In your resource's ListRecords page
protected function getHeaderWidgets(): array
{
    return [CategoryWidget::class];
}

Tree Pages

Standalone pages dedicated to tree management.

1. Generate the page:

php artisan make:filament-tree-page CategoryTree --model=Category

2. Register the page:

// In your PanelProvider
public function panel(Panel $panel): Panel
{
    return $panel
        ->pages([
            CategoryTree::class,
        ]);
}

Resource Tree Pages

Integrated tree pages within Filament resources.

1. Generate for resource:

php artisan make:filament-tree-page CategoryTree --resource=Category

2. Register in resource:

// In your CategoryResource
public static function getPages(): array
{
    return [
        'index' => Pages\ListCategories::route('/'),
        'create' => Pages\CreateCategory::route('/create'),
        'edit' => Pages\EditCategory::route('/{record}/edit'),
        'tree' => Pages\CategoryTree::route('/tree'), // Add this line
    ];
}

Tree Customization

Record Display

Customize how records appear in the tree:

Custom record titles:

public function getTreeRecordTitle(?\Illuminate\Database\Eloquent\Model $record = null): string
{
    if (!$record) return '';

    return "[{$record->id}] {$record->title}";
}

Record icons:

public function getTreeRecordIcon(?\Illuminate\Database\Eloquent\Model $record = null): ?string
{
    if ($record->parent_id != -1) {
        return null; // No icon for child records
    }

    return match ($record->title) {
        'Categories' => 'heroicon-o-tag',
        'Products' => 'heroicon-o-shopping-bag',
        'Settings' => 'heroicon-o-cog',
        default => 'heroicon-o-folder',
    };
}

Tree Actions

Configure actions that appear for each tree record:

Quick setup with boolean methods:

protected function hasDeleteAction(): bool { return true; }
protected function hasEditAction(): bool { return true; }
protected function hasViewAction(): bool { return false; }

Advanced action configuration:

protected function configureEditAction(EditAction $action): EditAction
{
    return $action
        ->slideOver()
        ->modalHeading('Edit Category')
        ->modalSubmitActionLabel('Save Changes');
}

protected function configureDeleteAction(DeleteAction $action): DeleteAction
{
    return $action
        ->requiresConfirmation()
        ->modalDescription('This will permanently delete the category and all subcategories.');
}

protected function configureViewAction(ViewAction $action): ViewAction
{
    return $action
        ->slideOver()
        ->modalWidth('2xl');
}

Toolbar Actions

Add global actions displayed above the tree (v3.1.0+):

protected function getTreeToolbarActions(): array
{
    return [
        \SolutionForest\FilamentTree\Actions\CreateAction::make()
            ->label('Add Category')
            ->icon('heroicon-o-plus'),
        \Filament\Actions\ExportAction::make()
            ->label('Export Tree'),
        \Filament\Actions\ImportAction::make()
            ->label('Import Categories'),
    ];
}

Note: Toolbar actions are only supported in version 3.1.0 and later.

Icons and Styling

Tree depth control:

protected static int $maxDepth = 4; // Limit nesting depth

Node collapsed state:

public function getNodeCollapsedState(?\Illuminate\Database\Eloquent\Model $record = null): bool
{
    return true; // Start with all nodes collapsed
}

Form Schemas

Define forms for different operations:

// Used for all operations (fallback)
protected function getFormSchema(): array
{
    return [
        TextInput::make('title')->required(),
        Textarea::make('description'),
    ];
}

// Specific schemas for different actions
protected function getCreateFormSchema(): array { /* ... */ }
protected function getEditFormSchema(): array { /* ... */ }
protected function getViewFormSchema(): array { /* ... */ }

Advanced Features

Translation Support

Integration with Spatie Laravel Translatable:

1. Setup your model:

use Filament\Actions\LocaleSwitcher;
use SolutionForest\FilamentTree\Concern\ModelTree;
use Spatie\Translatable\HasTranslations;

class Category extends Model
{
    use HasTranslations, ModelTree;

    protected $translatable = ['title'];
}

2. Configure your tree page:

use SolutionForest\FilamentTree\Concern\TreeRecords\Translatable;

class CategoryTree extends TreePage
{
    use Translatable;

    public function getTranslatableLocales(): array
    {
        return ['en', 'fr', 'es'];
    }

    protected function getActions(): array
    {
        return [LocaleSwitcher::make()];
    }
}

Custom Column Names

Override default column names if your table structure differs:

class Category extends Model
{
    use ModelTree;

    public function determineOrderColumnName(): string
    {
        return 'sort_order'; // Instead of 'order'
    }

    public function determineParentColumnName(): string
    {
        return 'parent_category_id'; // Instead of 'parent_id'
    }

    public function determineTitleColumnName(): string
    {
        return 'name'; // Instead of 'title'
    }

    public static function defaultParentKey(): int
    {
        return 0; // Instead of -1
    }
}

Node State Management

Performance optimization for large trees:

// Pre-collapse deep nodes to improve initial load
public function getNodeCollapsedState(?\Illuminate\Database\Eloquent\Model $record = null): bool
{
    return $record && $record->getDepth() > 2;
}

// Custom tree depth per implementation
protected static int $maxDepth = 5;

Conditional record display:

public function getTreeRecordTitle(?\Illuminate\Database\Eloquent\Model $record = null): string
{
    if (!$record) return '';

    $title = $record->title;

    // Add indicators
    if ($record->children()->count() > 0) {
        $title .= " ({$record->children()->count()})";
    }

    if (!$record->is_active) {
        $title = "🚫 " . $title;
    }

    return $title;
}

Configuration

The configuration file config/filament-tree.php allows you to customize default behavior:

<?php

return [
    /**
     * Default column names for tree structure
     */
    'column_name' => [
        'order' => 'order',
        'parent' => 'parent_id',
        'title' => 'title',
    ],

    /**
     * Default parent ID for root nodes
     */
    'default_parent_id' => -1,

    /**
     * Default children relationship key
     */
    'default_children_key_name' => 'children',
];

Publish additional resources:

# Publish views for customization
php artisan vendor:publish --tag="filament-tree-views"

# Publish translations
php artisan vendor:publish --tag="filament-tree-translations"

Best Practices

Database Design

Always use -1 as default for parent_id - required for proper tree functionality
Index the parent_id and order columns for better performance
Consider adding is_active or status columns for soft filtering

Performance

Limit tree depth with $maxDepth for better user experience
Use eager loading when accessing tree relationships in custom code
Consider starting with collapsed nodes for large trees

User Experience

Provide clear icons to distinguish node types
Use descriptive action labels and confirmation dialogs
Group related toolbar actions logically

Development

Use the Artisan generators for consistent code structure
Extend configuration methods rather than overriding entire actions
Test with deeply nested data to ensure performance

Development

Frontend Build Process

# Development with watch mode
npm run dev

# Production build
npm run build

# CSS only
npm run build:styles

# JavaScript only
npm run build:scripts

Testing

# Run all tests
composer test

# Code analysis
composer analyse

# Code formatting
composer lint

Contributing

See CONTRIBUTING for development guidelines.

Changelog

See the CHANGELOG for more information on what has changed recently.

Contributing

See CONTRIBUTING for details.

Security Vulnerabilities

If you discover any security related issues, please email info+package@solutionforest.net instead of using the issue tracker.

Credits

[Carly]
All Contributors

License

Filament Tree is open-sourced software licensed under the MIT license.

About Solution Forest

Solution Forest Web development agency based in Hong Kong. We help customers to solve their problems. We Love Open Soruces.

We have built a collection of best-in-class products:

VantagoAds: A self manage Ads Server, Simplify Your Advertising Strategy.
GatherPro.events: A Event Photos management tools, Streamline Your Event Photos.
Website CMS Management: Website CMS Management - Filament CMS Plugin
Filaletter: Filaletter - Filament Newsletter Plugin

solution-forest / filament-tree

Maintainers

Details

README

Filament Tree

Version Compatibility

Installation

Quick Start

1. Database Setup

2. Model Setup

3. Generate Tree Components

Implementation Options

Tree Widgets

Tree Pages

Resource Tree Pages

Tree Customization

Record Display

Tree Actions

Toolbar Actions

Icons and Styling

Form Schemas

Advanced Features

Translation Support

Custom Column Names

Node State Management

Configuration

Best Practices

Database Design

Performance

User Experience

Development

Development

Frontend Build Process

Testing

Contributing

Changelog

Contributing

Security Vulnerabilities

Credits

License

About Solution Forest