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

# Tabs

> [!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/tabs.md).

## Introduction

Some schemas can be long and complex. You may want to use tabs to reduce the number of components that are visible at once:

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

Tabs::make('Tabs')
    ->tabs([
        Tab::make('Tab 1')
            ->schema([
                // ...
            ]),
        Tab::make('Tab 2')
            ->schema([
                // ...
            ]),
        Tab::make('Tab 3')
            ->schema([
                // ...
            ]),
    ])
```

<details>
  <summary />

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

Loading preview

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

## Setting the default active tab

The first tab will be open by default. You can change the default open tab using the `activeTab()` method:

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

Tabs::make('Tabs')
    ->tabs([
        Tab::make('Tab 1')
            ->schema([
                // ...
            ]),
        Tab::make('Tab 2')
            ->schema([
                // ...
            ]),
        Tab::make('Tab 3')
            ->schema([
                // ...
            ]),
    ])
    ->activeTab(2)
```

<details>
  <summary />

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

## Setting a tab icon

Tabs may have an [icon](https://filament-34a8cf01.mintlify.site/4.x/styling/icons.md), which you can set using the `icon()` method:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Schemas\Components\Tabs;
use Filament\Schemas\Components\Tabs\Tab;
use Filament\Support\Icons\Heroicon;

Tabs::make('Tabs')
    ->tabs([
        Tab::make('Notifications')
            ->icon(Heroicon::Bell)
            ->schema([
                // ...
            ]),
        // ...
    ])
```

<details>
  <summary />

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

Loading preview

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

### Setting the tab icon position

The icon of the tab may be positioned before or after the label using the `iconPosition()` method:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Schemas\Components\Tabs;
use Filament\Schemas\Components\Tabs\Tab;
use Filament\Support\Enums\IconPosition;
use Filament\Support\Icons\Heroicon;

Tabs::make('Tabs')
    ->tabs([
        Tab::make('Notifications')
            ->icon(Heroicon::Bell)
            ->iconPosition(IconPosition::After)
            ->schema([
                // ...
            ]),
        // ...
    ])
```

<details>
  <summary />

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

Loading preview

![Tabs with icons after their labels](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/schemas/layout/tabs/icons-after.jpg)

## Setting a tab badge

Tabs may have a badge, which you can set using the `badge()` method:

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

Tabs::make('Tabs')
    ->tabs([
        Tab::make('Notifications')
            ->badge(5)
            ->schema([
                // ...
            ]),
        // ...
    ])
```

<details>
  <summary />

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

Loading preview

![Tabs with badges](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/schemas/layout/tabs/badges.jpg)

If you'd like to change the [color](https://filament-34a8cf01.mintlify.site/4.x/styling/colors.md) for a badge, you can use the `badgeColor()` method:

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

Tabs::make('Tabs')
    ->tabs([
        Tab::make('Notifications')
            ->badge(5)
            ->badgeColor('info')
            ->schema([
                // ...
            ]),
        // ...
    ])
```

<details>
  <summary />

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

Loading preview

![Tabs with badges with color](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/schemas/layout/tabs/badges-color.jpg)

### Deferring the loading of tab badges

If you have expensive queries powering your tab badges, the initial page load may be slow. You can defer the loading of tab badges using the `deferBadge()` method, which will load the badge values asynchronously after the page has rendered:

```php theme={"theme":"gruvbox-dark-hard"}
use App\Models\Notification;
use Filament\Schemas\Components\Tabs;
use Filament\Schemas\Components\Tabs\Tab;

Tabs::make('Tabs')
    ->key('notifications-tabs')
    ->tabs([
        Tab::make('Notifications')
            ->badge(static fn (): int => Notification::query()->where('unread', true)->count())
            ->deferBadge()
            ->schema([
                // ...
            ]),
        // ...
    ])
```

> [!WARNING]
>
> The `badge()` value must be returned from a function when using `deferBadge()`. If you pass a raw value like `badge(Notification::query()->count())`, the query runs immediately when the tab is built, defeating the purpose of deferral.
>
> The `Tabs` component must have a `key()` set when using `deferBadge()`. Without a key, the deferred badge request cannot identify the correct component on the server.

<details>
  <summary />

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

## Using grid columns within a tab

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

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

Tabs::make('Tabs')
    ->tabs([
        Tab::make('Tab 1')
            ->schema([
                // ...
            ])
            ->columns(3),
        // ...
    ])
```

<details>
  <summary />

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

## Disabling scrollable tabs

Tabs are rendered horizontally by default, and are scrollable when they exceed the available width.

You may disable scrolling using the `scrollable(false)` method:

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

Tabs::make('Tabs')
    ->tabs([
        // ...
    ])
    ->scrollable(false)
```

When tabs are not scrollable, the component automatically detects the available width. If not all tabs can fit, a dropdown button will appear. Any tabs that exceed the available width will be grouped inside this dropdown automatically.

Loading preview

![Non-scrollable tabs with overflow dropdown](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/schemas/layout/tabs/not-scrollable.jpg)

## Using vertical tabs

You can render the tabs vertically by using the `vertical()` method:

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

Tabs::make('Tabs')
    ->tabs([
        Tab::make('Tab 1')
            ->schema([
                // ...
            ]),
        Tab::make('Tab 2')
            ->schema([
                // ...
            ]),
        Tab::make('Tab 3')
            ->schema([
                // ...
            ]),
    ])
    ->vertical()
```

Loading preview

![Vertical tabs](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/schemas/layout/tabs/vertical.jpg)

Optionally, you can pass a boolean value to the `vertical()` method to control if the tabs should be rendered vertically or not:

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

Tabs::make('Tabs')
    ->tabs([
        // ...
    ])
    ->vertical(FeatureFlag::active())
```

<details>
  <summary />

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

## Removing the styled container

By default, tabs and their content are wrapped in a container styled as a card. You may remove the styled container using `contained()`:

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

Tabs::make('Tabs')
    ->tabs([
        Tab::make('Tab 1')
            ->schema([
                // ...
            ]),
        Tab::make('Tab 2')
            ->schema([
                // ...
            ]),
        Tab::make('Tab 3')
            ->schema([
                // ...
            ]),
    ])
    ->contained(false)
```

<details>
  <summary />

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

Loading preview

![Tabs without a styled container](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/schemas/layout/tabs/not-contained.jpg)

## Disabling fields in a tab

Calling `disabled()` on a `Tab` disables its fields, not its header. The tab remains available so users can read its content.

## Setting unique tab IDs

If you set custom `id()` values, keep them unique across the page so headers remain associated with the correct panels. Use distinct keys for separate tabsets, including nested tabsets with the same tab labels.

## Persisting the current tab in the user's session

By default, the current tab is not persisted in the browser's local storage. You can change this behavior using the `persistTab()` method. You must also pass in a unique `id()` for the tabs component, to distinguish it from all other sets of tabs in the app. This ID will be used as the key in the local storage to store the current tab:

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

Tabs::make('Tabs')
    ->tabs([
        // ...
    ])
    ->persistTab()
    ->id('order-tabs')
```

Optionally, the `persistTab()` method accepts a boolean value to control if the active tab should persist or not:

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

Tabs::make('Tabs')
    ->tabs([
        // ...
    ])
    ->persistTab(FeatureFlag::active())
    ->id('order-tabs')
```

<details>
  <summary />

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

## Persisting the current tab in the URL's query string

By default, the current tab is not persisted in the URL's query string. You can change this behavior using the `persistTabInQueryString()` method:

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

Tabs::make('Tabs')
    ->tabs([
        Tab::make('Tab 1')
            ->schema([
                // ...
            ]),
        Tab::make('Tab 2')
            ->schema([
                // ...
            ]),
        Tab::make('Tab 3')
            ->schema([
                // ...
            ]),
    ])
    ->persistTabInQueryString()
```

When enabled, the current tab is persisted in the URL's query string using the `tab` key. You can change this key by passing it to the `persistTabInQueryString()` method:

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

Tabs::make('Tabs')
    ->tabs([
        Tab::make('Tab 1')
            ->schema([
                // ...
            ]),
        Tab::make('Tab 2')
            ->schema([
                // ...
            ]),
        Tab::make('Tab 3')
            ->schema([
                // ...
            ]),
    ])
    ->persistTabInQueryString('settings-tab')
```

<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 tab content

If the content of a tab is expensive to render, you can pass a `Schema` object to its `schema()` method and use `deferLoading()`. The content of the active tab will be loaded when it enters the viewport. The content of an inactive tab will not be loaded until the tab is selected:

```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms\Components\TextInput;
use Filament\Schemas\Components\Tabs;
use Filament\Schemas\Components\Tabs\Tab;
use Filament\Schemas\Schema;

Tabs::make('Settings')
    ->key('settingsTabs')
    ->tabs([
        Tab::make('Profile')
            ->key('profileTab')
            ->schema(
                Schema::make()
                    ->components([
                        TextInput::make('name'),
                    ])
                    ->deferLoading(),
            ),
        Tab::make('Notifications')
            ->key('notificationsTab')
            ->schema(
                Schema::make()
                    ->components([
                        // ...
                    ])
                    ->deferLoading(),
            ),
    ])
```

Every deferred schema must have a unique key. In this example, the keys on the tabs are inherited by their child schemas, while the key on the `Tabs` component namespaces them from other tabs in the same schema. 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).

## Using tabs without content panels

If your `livewireProperty()` tabs change a filter instead of showing separate content panels, use `tabPanels(false)`. This renders a labelled group of buttons with a pressed state rather than a tablist:

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

Tabs::make('Status')
    ->livewireProperty('activeStatus')
    ->tabPanels(false)
    ->tabs([
        'all' => Tab::make('All'),
        'published' => Tab::make('Published'),
    ])
```

Resource list filters use this mode automatically. For links that navigate to another page, use the [tabs Blade component](https://filament-34a8cf01.mintlify.site/4.x/components/tabs.md) instead. Navigation links keep their native link behavior and are not schema tab panels.

[Edit this page on GitHub](https://github.com/filamentphp/filament/edit/4.x/packages/schemas/docs/04-tabs.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.