Sections

Introduction

You may want to separate your fields into sections, each with a heading and description. To do this, you can use a section component:

use Filament\Schemas\Components\Section;

Section::make('Rate limiting')
    ->description('Prevent abuse by limiting the number of requests per period')
    ->schema([
        // ...
    ])

As well as allowing static values, the make() and description() methods also accept functions to dynamically calculate them. You can inject various utilities into the function as parameters.

You can also use a section without a header, which just wraps the components in a simple card:

use Filament\Schemas\Components\Section;

Section::make()
    ->schema([
        // ...
    ])

Adding an icon to the section's header

You may add an icon to the section's header using the icon() method:

use Filament\Schemas\Components\Section;
use Filament\Support\Icons\Heroicon;

Section::make('Cart')
    ->description('The items you have selected for purchase')
    ->icon(Heroicon::ShoppingBag)
    ->schema([
        // ...
    ])

As well as allowing a static value, the icon() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Positioning the heading and description aside

You may use the aside() to align heading & description on the left, and the components inside a card on the right:

use Filament\Schemas\Components\Section;

Section::make('Rate limiting')
    ->description('Prevent abuse by limiting the number of requests per period')
    ->aside()
    ->schema([
        // ...
    ])

Optionally, you may pass a boolean value to control if the section should be aside or not:

use Filament\Schemas\Components\Section;

Section::make('Rate limiting')
    ->description('Prevent abuse by limiting the number of requests per period')
    ->aside(FeatureFlag::active())
    ->schema([
        // ...
    ])

As well as allowing a static value, the aside() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Positioning the content before the heading

Use contentBefore() with aside() to position the content before the heading and description on medium and larger screens:

use Filament\Schemas\Components\Section;

Section::make('Rate limiting')
    ->aside()
    ->contentBefore()
    ->schema([
        // ...
    ])

You may pass a boolean or a closure to contentBefore() to control this condition.

Collapsing sections

Sections may be collapsible() to optionally hide long content:

use Filament\Schemas\Components\Section;

Section::make('Cart')
    ->description('The items you have selected for purchase')
    ->schema([
        // ...
    ])
    ->collapsible()

Your sections may be collapsed() by default:

use Filament\Schemas\Components\Section;

Section::make('Cart')
    ->description('The items you have selected for purchase')
    ->schema([
        // ...
    ])
    ->collapsed()

Optionally, the collapsible() and collapsed() methods accept a boolean value to control if the section should be collapsible and collapsed or not:

use Filament\Schemas\Components\Section;

Section::make('Cart')
    ->description('The items you have selected for purchase')
    ->schema([
        // ...
    ])
    ->collapsible(FeatureFlag::active())
    ->collapsed(FeatureFlag::active())

As well as allowing static values, the collapsible() and collapsed() methods also accept functions to dynamically calculate it. You can inject various utilities into the function as parameters.

If a collapsed section contains components that are expensive to render, you can lazy load its content when the section is expanded.

Persisting collapsed sections in the user's session

You can persist whether a section is collapsed in local storage using the persistCollapsed() method, so it will remain collapsed when the user refreshes the page:

use Filament\Schemas\Components\Section;

Section::make('Cart')
    ->description('The items you have selected for purchase')
    ->schema([
        // ...
    ])
    ->collapsible()
    ->persistCollapsed()

To persist the collapse state, the local storage needs a unique ID to store the state. This ID is generated based on the heading of the section. If your section does not have a heading, or if you have multiple sections with the same heading that you do not want to collapse together, you can manually specify the id() of that section to prevent an ID conflict:

use Filament\Schemas\Components\Section;

Section::make('Cart')
    ->description('The items you have selected for purchase')
    ->schema([
        // ...
    ])
    ->collapsible()
    ->persistCollapsed()
    ->id('order-cart')

Optionally, the persistCollapsed() method accepts a boolean value to control if the section should persist its collapsed state or not:

use Filament\Schemas\Components\Section;

Section::make('Cart')
    ->description('The items you have selected for purchase')
    ->schema([
        // ...
    ])
    ->collapsible()
    ->persistCollapsed(FeatureFlag::active())

As well as allowing static values, the persistCollapsed() and id() methods also accept functions to dynamically calculate them. You can inject various utilities into the function as parameters.

Compact section styling

When nesting sections, you can use a more compact styling:

use Filament\Schemas\Components\Section;

Section::make('Rate limiting')
    ->description('Prevent abuse by limiting the number of requests per period')
    ->schema([
        // ...
    ])
    ->compact()

Optionally, the compact() method accepts a boolean value to control if the section should be compact or not:

use Filament\Schemas\Components\Section;

Section::make('Rate limiting')
    ->description('Prevent abuse by limiting the number of requests per period')
    ->schema([
        // ...
    ])
    ->compact(FeatureFlag::active())

As well as allowing a static value, the compact() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Secondary section styling

By default, sections have a contrasting background color, which makes them stand out against a gray background. Secondary styling gives the section a less contrasting background, so it is usually slightly darker. This is a better styling when the background color behind the section is the same color as the default section background color, for example when a section is nested inside another section. Secondary sections can be created using the secondary() method:

use Filament\Schemas\Components\Section;

Section::make('Notes')
    ->schema([
        // ...
    ])
    ->secondary()
    ->compact()

Optionally, the secondary() method accepts a boolean value to control if the section should be secondary or not:

use Filament\Schemas\Components\Section;

Section::make('Notes')
    ->schema([
        // ...
    ])
    ->secondary(FeatureFlag::active())

Inserting actions and other components in the header of a section

You may insert actions and any other schema component (usually prime components) into the header of a section by passing an array of components to the afterHeader() method:

use Filament\Actions\Action;
use Filament\Schemas\Components\Section;

Section::make('Rate limiting')
    ->description('Prevent abuse by limiting the number of requests per period')
    ->afterHeader([
        Action::make('test'),
    ])
    ->schema([
        // ...
    ])

As well as allowing a static value, the afterHeader() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Inserting actions and other components in the footer of a section

You may insert actions and any other schema component (usually prime components) into the footer of a section by passing an array of components to the footer() method:

use Filament\Actions\Action;
use Filament\Schemas\Components\Section;

Section::make('Rate limiting')
    ->description('Prevent abuse by limiting the number of requests per period')
    ->schema([
        // ...
    ])
    ->footer([
        Action::make('test'),
    ])

As well as allowing a static value, the footer() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Using grid columns within a section

You may use the columns() method to easily create a grid within the section:

use Filament\Schemas\Components\Section;

Section::make('Heading')
    ->schema([
        // ...
    ])
    ->columns(2)

As well as allowing a static value, the columns() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Lazy loading section content

If the content of a section is expensive to render, you can pass a Schema object to schema() and use lazyLoaded(). This is particularly useful for a section that is collapsed by default. The section and its header will render immediately, while its content will not be loaded until the section is expanded and the content enters the viewport:

use Filament\Forms\Components\TextInput;
use Filament\Schemas\Components\Section;
use Filament\Schemas\Schema;

Section::make('Customer details')
    ->key('customerDetails')
    ->schema(
        Schema::make()
            ->components([
                TextInput::make('name'),
                TextInput::make('email')
                    ->email(),
            ])
            ->lazyLoaded(),
    )
    ->collapsed()

Every lazy schema must have a unique key. In this example, the child schema inherits its key from the section. You can learn more in the schema overview.