Sections

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

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([
        // ...
    ])

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([
        // ...
    ])

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([
        // ...
    ])

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())

If a collapsed section contains components that are expensive to render, you can defer the loading of its content until 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())

Deferring the loading of section content

If the content of a section is expensive to render, you can pass a Schema object to schema() and use deferLoading(). 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(),
            ])
            ->deferLoading(),
    )
    ->collapsed()

Every deferred 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.

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())

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\Schemas\Components\Section;

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

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\Schemas\Components\Section;

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

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)

Introduction

Guides

Resources

Tables

Schemas

Forms

Infolists

Actions

Notifications

Widgets

Configuration

Navigation

Users

Styling

Advanced

Testing

Plugins

Components

Deployment

Upgrading

Introduction

Adding an icon to the section’s header

Positioning the heading and description aside

Collapsing sections

Persisting collapsed sections in the user’s session

Deferring the loading of section content

Compact section styling

Secondary section styling

Inserting actions and other components in the header of a section

Inserting actions and other components in the footer of a section

Using grid columns within a section

​Introduction

​Adding an icon to the section’s header

​Positioning the heading and description aside

​Collapsing sections

​Persisting collapsed sections in the user’s session

​Deferring the loading of section content

​Compact section styling

​Secondary section styling

​Inserting actions and other components in the header of a section

​Inserting actions and other components in the footer of a section

​Using grid columns within a section

Introduction

Adding an icon to the section’s header

Positioning the heading and description aside

Collapsing sections

Persisting collapsed sections in the user’s session

Deferring the loading of section content

Compact section styling

Secondary section styling

Inserting actions and other components in the header of a section

Inserting actions and other components in the footer of a section

Using grid columns within a section