Getting started - Filament

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

Overview

Introduction to Filament

Watch the Rapid Laravel Development with Filament series on Laracasts - it will teach you how to get started with the resources.

Play Video Laracasts

Kevin McKee

Instructor

Resources are static classes that are used to build CRUD interfaces for your Eloquent models. They describe how administrators should be able to interact with data from your app - using tables and forms.

Creating a resource

To create a resource for the App\Models\Customer model:

php artisan make:filament-resource Customer

This will create several files in the app/Filament/Resources directory:

.
+-- CustomerResource.php
+-- CustomerResource
|   +-- Pages
|   |   +-- CreateCustomer.php
|   |   +-- EditCustomer.php
|   |   +-- ListCustomers.php

Your new resource class lives in CustomerResource.php. The classes in the Pages directory are used to customize the pages in the app that interact with your resource. They’re all full-page Livewire components that you can customize in any way you wish.

Have you created a resource, but it’s not appearing in the navigation menu? If you have a model policy, make sure you return true from the viewAny() method.

Sometimes, your models are simple enough that you only want to manage records on one page, using modals to create, edit and delete records. To generate a simple resource with modals:

php artisan make:filament-resource Customer --simple

Your resource will have a “Manage” page, which is a List page with modals added. Additionally, your simple resource will have no getRelations() method, as relation managers are only displayed on the Edit and View pages, which are not present in simple resources. Everything else is the same.

Automatically generating forms and tables

If you’d like to save time, Filament can automatically generate the form and table for you, based on your model’s database columns, using --generate:

php artisan make:filament-resource Customer --generate

Handling soft deletes

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

php artisan make:filament-resource Customer --soft-deletes

You can find out more about soft deleting here.

Generating a View page

By default, only List, Create and Edit pages are generated for your resource. If you’d also like a View page, use the --view flag:

php artisan make:filament-resource Customer --view

Specifiying a custom model namespace

By default, Filament will assume that your model exists in the App\Models directory. You can pass a different namespace for the model using the --model-namespace flag:

php artisan make:filament-resource Customer --model-namespace=Custom\\Path\\Models

In this example, the model should exist at Custom\Path\Models\Customer. Please note the double backslashes \\ in the command that are required. Now when generating the resource, Filament will be able to locate the model and read the database schema.

Generating the model, migration and factory at the same name

If you’d like to save time when scaffolding your resources, Filament can also generate the model, migration and factory for the new resource at the same time using the --model, --migration and --factory flags in any combination:

php artisan make:filament-resource Customer --model --migration --factory

Record titles

A $recordTitleAttribute may be set for your resource, which is the name of the column on your model that can be used to identify it from others. For example, this could be a blog post’s title or a customer’s name:

protected static ?string $recordTitleAttribute = 'name';

This is required for features like global search to work.

You may specify the name of an Eloquent accessor if just one column is inadequate at identifying a record.

Resource forms

Basic Form Inputs

Watch the Rapid Laravel Development with Filament series on Laracasts - it will teach you the basics of adding a form to your resource.

Play Video Laracasts

Kevin McKee

Instructor

Resource classes contain a form() method that is used to build the forms on the Create and Edit pages:

use Filament\Forms;
use Filament\Forms\Form;

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

The schema() method is used to define the structure of your form. It is an array of fields and layout components, in the order they should appear in your form. Check out the Forms docs for a guide on how to build forms with Filament.

Hiding components based on the current operation

The hiddenOn() method of form components allows you to dynamically hide fields based on the current page or action. In this example, we hide the password field on the edit page:

use Livewire\Component;

Forms\Components\TextInput::make('password')
    ->password()
    ->required()
    ->hiddenOn('edit'),

Alternatively, we have a visibleOn() shortcut method for only showing a field on one page or action:

use Livewire\Component;

Forms\Components\TextInput::make('password')
    ->password()
    ->required()
    ->visibleOn('create'),

Resource tables

Table Columns

Watch the Rapid Laravel Development with Filament series on Laracasts - it will teach you the basics of adding a table to your resource.

Play Video Laracasts

Kevin McKee

Instructor

Resource classes contain a table() method that is used to build the table on the List page:

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

public static function table(Table $table): Table
{
    return $table
        ->columns([
            Tables\Columns\TextColumn::make('name'),
            Tables\Columns\TextColumn::make('email'),
            // ...
        ])
        ->filters([
            Tables\Filters\Filter::make('verified')
                ->query(fn (Builder $query): Builder => $query->whereNotNull('email_verified_at')),
            // ...
        ])
        ->actions([
            Tables\Actions\EditAction::make(),
        ])
        ->bulkActions([
            Tables\Actions\BulkActionGroup::make([
                Tables\Actions\DeleteBulkAction::make(),
            ]),
        ]);
}

Check out the tables docs to find out how to add table columns, filters, actions and more.

Authorization

For authorization, Filament will observe any model policies that are registered in your app. The following methods are used:

viewAny() is used to completely hide resources from the navigation menu, and prevents the user from accessing any pages.
create() is used to control creating new records.
update() is used to control editing a record.
view() is used to control viewing a record.
delete() is used to prevent a single record from being deleted. deleteAny() is used to prevent records from being bulk deleted. Filament uses the deleteAny() method because iterating through multiple records and checking the delete() policy is not very performant.
forceDelete() is used to prevent a single soft-deleted record from being force-deleted. forceDeleteAny() is used to prevent records from being bulk force-deleted. Filament uses the forceDeleteAny() method because iterating through multiple records and checking the forceDelete() policy is not very performant.
restore() is used to prevent a single soft-deleted record from being restored. restoreAny() is used to prevent records from being bulk restored. Filament uses the restoreAny() method because iterating through multiple records and checking the restore() policy is not very performant.
reorder() is used to control reordering a record.

Skipping authorization

If you’d like to skip authorization for a resource, you may set the $shouldSkipAuthorization property to true:

protected static bool $shouldSkipAuthorization = true;

Customizing the model label

Each resource has a “model label” which is automatically generated from the model name. For example, an App\Models\Customer model will have a customer label. The label is used in several parts of the UI, and you may customize it using the $modelLabel property:

protected static ?string $modelLabel = 'cliente';

Alternatively, you may use the getModelLabel() to define a dynamic label:

public static function getModelLabel(): string
{
    return __('filament/resources/customer.label');
}

Customizing the plural model label

Resources also have a “plural model label” which is automatically generated from the model label. For example, a customer label will be pluralized into customers. You may customize the plural version of the label using the $pluralModelLabel property:

protected static ?string $pluralModelLabel = 'clientes';

Alternatively, you may set a dynamic plural label in the getPluralModelLabel() method:

public static function getPluralModelLabel(): string
{
    return __('filament/resources/customer.plural_label');
}

Automatic model label capitalization

By default, Filament will automatically capitalize each word in the model label, for some parts of the UI. For example, in page titles, the navigation menu, and the breadcrumbs. If you want to disable this behavior for a resource, you can set $hasTitleCaseModelLabel in the resource:

protected static bool $hasTitleCaseModelLabel = false;

Filament will automatically generate a navigation menu item for your resource using the plural label. If you’d like to customize the navigation item label, you may use the $navigationLabel property:

protected static ?string $navigationLabel = 'Mis Clientes';

Alternatively, you may set a dynamic navigation label in the getNavigationLabel() method:

public static function getNavigationLabel(): string
{
    return __('filament/resources/customer.navigation_label');
}

The $navigationIcon property supports the name of any Blade component. By default, Heroicons are installed. However, you may create your own custom icon components or install an alternative library if you wish.

protected static ?string $navigationIcon = 'heroicon-o-user-group';

Alternatively, you may set a dynamic navigation icon in the getNavigationIcon() method:

use Illuminate\Contracts\Support\Htmlable;

public static function getNavigationIcon(): string | Htmlable | null
{
    return 'heroicon-o-user-group';
}

The $navigationSort property allows you to specify the order in which navigation items are listed:

protected static ?int $navigationSort = 2;

Alternatively, you may set a dynamic navigation item order in the getNavigationSort() method:

public static function getNavigationSort(): ?int
{
    return 2;
}

You may group navigation items by specifying a $navigationGroup property:

protected static ?string $navigationGroup = 'Shop';

Alternatively, you may use the getNavigationGroup() method to set a dynamic group label:

public static function getNavigationGroup(): ?string
{
    return __('filament/navigation.groups.shop');
}

You may group navigation items as children of other items, by passing the label of the parent item as the $navigationParentItem:

protected static ?string $navigationParentItem = 'Products';

protected static ?string $navigationGroup = 'Shop';

As seen above, if the parent item has a navigation group, that navigation group must also be defined, so the correct parent item can be identified. You may also use the getNavigationParentItem() method to set a dynamic parent item label:

public static function getNavigationParentItem(): ?string
{
    return __('filament/navigation.groups.shop.items.products');
}

If you’re reaching for a third level of navigation like this, you should consider using clusters instead, which are a logical grouping of resources and custom pages, which can share their own separate navigation.

Generating URLs to resource pages

Filament provides getUrl() static method on resource classes to generate URLs to resources and specific pages within them. Traditionally, you would need to construct the URL by hand or by using Laravel’s route() helper, but these methods depend on knowledge of the resource’s slug or route naming conventions. The getUrl() method, without any arguments, will generate a URL to the resource’s List page:

use App\Filament\Resources\CustomerResource;

CustomerResource::getUrl(); // /admin/customers

You may also generate URLs to specific pages within the resource. The name of each page is the array key in the getPages() array of the resource. For example, to generate a URL to the Create page:

use App\Filament\Resources\CustomerResource;

CustomerResource::getUrl('create'); // /admin/customers/create

Some pages in the getPages() method use URL parameters like record. To generate a URL to these pages and pass in a record, you should use the second argument:

use App\Filament\Resources\CustomerResource;

CustomerResource::getUrl('edit', ['record' => $customer]); // /admin/customers/edit/1

In this example, $customer can be an Eloquent model object, or an ID.

Generating URLs to resource modals

This can be especially useful if you are using simple resources with only one page. To generate a URL for an action in the resource’s table, you should pass the tableAction and tableActionRecord as URL parameters:

use App\Filament\Resources\CustomerResource;
use Filament\Tables\Actions\EditAction;

CustomerResource::getUrl(parameters: [
    'tableAction' => EditAction::getDefaultName(),
    'tableActionRecord' => $customer,
]); // /admin/customers?tableAction=edit&tableActionRecord=1

Or if you want to generate a URL for an action on the page like a CreateAction in the header, you can pass it in to the action parameter:

use App\Filament\Resources\CustomerResource;
use Filament\Actions\CreateAction;

CustomerResource::getUrl(parameters: [
    'action' => CreateAction::getDefaultName(),
]); // /admin/customers?action=create

Generating URLs to resources in other panels

If you have multiple panels in your app, getUrl() will generate a URL within the current panel. You can also indicate which panel the resource is associated with, by passing the panel ID to the panel argument:

use App\Filament\Resources\CustomerResource;

CustomerResource::getUrl(panel: 'marketing');

Customizing the resource Eloquent query

Within Filament, every query to your resource model will start with the getEloquentQuery() method. Because of this, it’s very easy to apply your own query constraints or model scopes that affect the entire resource:

public static function getEloquentQuery(): Builder
{
    return parent::getEloquentQuery()->where('is_active', true);
}

Disabling global scopes

By default, Filament will observe all global scopes that are registered to your model. However, this may not be ideal if you wish to access, for example, soft deleted records. To overcome this, you may override the getEloquentQuery() method that Filament uses:

public static function getEloquentQuery(): Builder
{
    return parent::getEloquentQuery()->withoutGlobalScopes();
}

Alternatively, you may remove specific global scopes:

public static function getEloquentQuery(): Builder
{
    return parent::getEloquentQuery()->withoutGlobalScopes([ActiveScope::class]);
}

More information about removing global scopes may be found in the Laravel documentation.

Customizing the resource URL

By default, Filament will generate a URL based on the name of the resource. You can customize this by setting the $slug property on the resource:

protected static ?string $slug = 'pending-orders';

Sub-navigation allows the user to navigate between different pages within a resource. Typically, all pages in the sub-navigation will be related to the same record in the resource. For example, in a Customer resource, you may have a sub-navigation with the following pages:

View customer, a ViewRecord page that provides a read-only view of the customer’s details.
Edit customer, an EditRecord page that allows the user to edit the customer’s details.
Edit customer contact, an EditRecord page that allows the user to edit the customer’s contact details. You can learn how to create more than one Edit page.
Manage addresses, a ManageRelatedRecords page that allows the user to manage the customer’s addresses.
Manage payments, a ManageRelatedRecords page that allows the user to manage the customer’s payments.

To add a sub-navigation to each “singular record” page in the resource, you can add the getRecordSubNavigation() method to the resource class:

use App\Filament\Resources\CustomerResource\Pages;
use Filament\Resources\Pages\Page;

public static function getRecordSubNavigation(Page $page): array
{
    return $page->generateNavigationItems([
        Pages\ViewCustomer::class,
        Pages\EditCustomer::class,
        Pages\EditCustomerContact::class,
        Pages\ManageCustomerAddresses::class,
        Pages\ManageCustomerPayments::class,
    ]);
}

Each item in the sub-navigation can be customized using the same navigation methods as normal pages.

If you’re looking to add sub-navigation to switch between entire resources and custom pages, you might be looking for clusters, which are used to group these together. The getRecordSubNavigation() method is intended to construct a navigation between pages that relate to a particular record inside a resource.

The sub-navigation is rendered at the start of the page by default. You may change the position by setting the $subNavigationPosition property on the resource. The value may be SubNavigationPosition::Start, SubNavigationPosition::End, or SubNavigationPosition::Top to render the sub-navigation as tabs:

use Filament\Pages\SubNavigationPosition;

protected static SubNavigationPosition $subNavigationPosition = SubNavigationPosition::End;

Deleting resource pages

If you’d like to delete a page from your resource, you can just delete the page file from the Pages directory of your resource, and its entry in the getPages() method. For example, you may have a resource with records that may not be created by anyone. Delete the Create page file, and then remove it from getPages():

public static function getPages(): array
{
    return [
        'index' => Pages\ListCustomers::route('/'),
        'edit' => Pages\EditCustomer::route('/{record}/edit'),
    ];
}

Deleting a page will not delete any actions that link to that page. Any actions will open a modal instead of sending the user to the non-existent page. For instance, the CreateAction on the List page, the EditAction on the table or View page, or the ViewAction on the table or Edit page. If you want to remove those buttons, you must delete the actions as well.

Edit this page on GitHub

Panels

Tables

Forms

Infolists

Actions

Notifications

Widgets

Core concepts

​Overview

Introduction to Filament

​Creating a resource

​Simple (modal) resources

​Automatically generating forms and tables

​Handling soft deletes

​Generating a View page

​Specifiying a custom model namespace

​Generating the model, migration and factory at the same name

​Record titles

​Resource forms

Basic Form Inputs

​Hiding components based on the current operation

​Resource tables

Table Columns

​Authorization

​Skipping authorization

​Customizing the model label

​Customizing the plural model label

​Automatic model label capitalization

​Resource navigation items

​Setting a resource navigation icon

​Sorting resource navigation items

​Grouping resource navigation items

​Grouping resource navigation items under other items

​Generating URLs to resource pages

​Generating URLs to resource modals

​Generating URLs to resources in other panels

​Customizing the resource Eloquent query

​Disabling global scopes

​Customizing the resource URL

​Resource sub-navigation

​Sub-navigation position

​Deleting resource pages

Sponsored by

Overview

Creating a resource

Simple (modal) resources

Automatically generating forms and tables

Handling soft deletes

Generating a View page

Specifiying a custom model namespace

Generating the model, migration and factory at the same name

Record titles

Resource forms

Hiding components based on the current operation

Resource tables

Authorization

Skipping authorization

Customizing the model label

Customizing the plural model label

Automatic model label capitalization

Resource navigation items

Setting a resource navigation icon

Sorting resource navigation items

Grouping resource navigation items

Grouping resource navigation items under other items

Generating URLs to resource pages

Generating URLs to resource modals

Generating URLs to resources in other panels

Customizing the resource Eloquent query

Disabling global scopes

Customizing the resource URL

Resource sub-navigation

Sub-navigation position

Deleting resource pages