Filament Navigation with Clusters: Main Things You Need to Know

Filament allows you to create clusters to group resources and custom pages. In this tutorial, we will explore all the options and how they look visually.

Before creating a cluster, you need to tell the panel where the cluster classes will be located. To do that, you would use discoverClusters() in the panel provider.

return $panel
    ->default()
    ->id('admin')
    ->login()
    ->discoverClusters(in: app_path('Filament/Clusters'), for: 'App\\Filament\\Clusters') 
    ->discoverResources(in: app_path('Filament/Resources'), for: 'App\\Filament\\Resources')
    ->discoverPages(in: app_path('Filament/Pages'), for: 'App\\Filament\\Pages')
    // ...

Now, you can create a cluster with an Artisan command:

php artisan make:filament-cluster Products

This will create a Products navigation item. To add a resource or custom page to a cluster, specify the cluster class on the $cluster property in the desired class to be added.

use App\Filament\Clusters\Products;
 
class ProductResource extends Resource
{
    protected static ?string $model = Product::class;
 
    protected static ?string $cluster = Products::class; 
 
    // ...
}

When using clusters Filament have a recommended way to structure them:

+-- Clusters
|   +-- Settings.php
|   +-- Settings
|   |   +-- Pages
|   |   |   +-- ManageBranding.php
|   |   |   +-- ManageNotifications.php
|   |   +-- Resources
|   |   |   +-- ColorResource.php
|   |   |   +-- ColorResource
|   |   |   |   +-- Pages
|   |   |   |   |   +-- CreateColor.php
|   |   |   |   |   +-- EditColor.php
|   |   |   |   |   +-- ListColors.php

When you create a resource or a custom page using an Artisan command, you will be asked if you want to create it in a cluster.

You can customize clusters breadcrumb using the $clusterBreadcrumb property or the getClusterBreadcrumb() method.

use Filament\Clusters\Cluster;
 
class Products extends Cluster
{
    protected static ?string $navigationIcon = 'heroicon-o-squares-2x2';
 
    protected static ?string $navigationGroup = 'Shop';
 
    protected static ?string $clusterBreadcrumb = 'Cluster'; 
}

If you want to see clusters in action, we have a premium example Filament Create/Edit Pages: Add Cluster-like Sub-Navigation Items.