> ## Documentation Index
> Fetch the complete documentation index at: https://filament-34a8cf01.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Sections

> [!WARNING]
>
> 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](https://filament-34a8cf01.mintlify.site/5.x/schemas/sections.md).

## 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:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Schemas\Components\Section;

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

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/schemas/overview.md#component-utility-injection)
</details>

Loading preview

![Section](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/schemas/layout/section/simple.jpg)

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

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Schemas\Components\Section;

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

Loading preview

![Section without header](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/schemas/layout/section/without-header.jpg)

## Adding an icon to the section's header

You may add an [icon](https://filament-34a8cf01.mintlify.site/4.x/styling/icons.md) to the section's header using the `icon()` method:

```php theme={"theme":"gruvbox-dark-hard"}
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([
        // ...
    ])
```

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/schemas/overview.md#component-utility-injection)
</details>

Loading preview

![Section with icon](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/schemas/layout/section/icons.jpg)

## 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:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Schemas\Components\Section;

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

Loading preview

![Section with heading and description aside](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/schemas/layout/section/aside.jpg)

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

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Schemas\Components\Section;

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

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/schemas/overview.md#component-utility-injection)
</details>

## Collapsing sections

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

```php theme={"theme":"gruvbox-dark-hard"}
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:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Schemas\Components\Section;

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

Loading preview

![Collapsed section](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/schemas/layout/section/collapsed.jpg)

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

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Schemas\Components\Section;

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

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/schemas/overview.md#component-utility-injection)
</details>

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

```php theme={"theme":"gruvbox-dark-hard"}
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:

```php theme={"theme":"gruvbox-dark-hard"}
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:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Schemas\Components\Section;

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

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/schemas/overview.md#component-utility-injection)
</details>

## Compact section styling

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

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Schemas\Components\Section;

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

Loading preview

![Compact section](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/schemas/layout/section/compact.jpg)

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

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Schemas\Components\Section;

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

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/schemas/overview.md#component-utility-injection)
</details>

## 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:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Schemas\Components\Section;

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

Loading preview

![Secondary section](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/schemas/layout/section/secondary.jpg)

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

```php theme={"theme":"gruvbox-dark-hard"}
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](../actions) and any other schema component (usually [prime components](https://filament-34a8cf01.mintlify.site/4.x/schemas/primes.md)) into the header of a section by passing an array of components to the `afterHeader()` method:

```php theme={"theme":"gruvbox-dark-hard"}
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([
        // ...
    ])
```

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/schemas/overview.md#component-utility-injection)
</details>

Loading preview

![Section with actions in the header](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/schemas/layout/section/header/actions.jpg)

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

You may insert [actions](../actions) and any other schema component (usually [prime components](https://filament-34a8cf01.mintlify.site/4.x/schemas/primes.md)) into the footer of a section by passing an array of components to the `footer()` method:

```php theme={"theme":"gruvbox-dark-hard"}
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'),
    ])
```

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/schemas/overview.md#component-utility-injection)
</details>

Loading preview

![Section with actions in the footer](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/schemas/layout/section/footer/actions.jpg)

## Using grid columns within a section

You may use the `columns()` method to easily create a [grid](https://filament-34a8cf01.mintlify.site/4.x/schemas/layouts.md#grid-system) within the section:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Schemas\Components\Section;

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

Loading preview

![Section with grid columns](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/schemas/layout/section/columns.jpg)

<details>
  <summary />

  [Learn more about utility injection.](https://filament-34a8cf01.mintlify.site/4.x/schemas/overview.md#component-utility-injection)
</details>

## 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](#collapsing-sections) 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:

```php theme={"theme":"gruvbox-dark-hard"}
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](https://filament-34a8cf01.mintlify.site/4.x/schemas/overview.md#deferring-the-loading-of-a-child-schema).

[Edit this page on GitHub](https://github.com/filamentphp/filament/edit/4.x/packages/schemas/docs/03-sections.md)

## Sponsored by

[Your logo here](https://github.com/sponsors/danharrin)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.