TallStackUI, Breadcrumbs

# Concept

The breadcrumbs component displays a navigation trail of links helping users understand their position within the application hierarchy. You can provide items manually as an array or let the component auto-resolve them from a route-based breadcrumb registry.

# Basic Usage

<x-breadcrumbs :items="[
    ['label' => 'Home', 'link' => '/'],
    ['label' => 'Users', 'link' => '/users'],
    ['label' => 'John Doe'],
]" />

# Named Routes

The link field accepts both URLs and Laravel named routes. Values starting with / or http are kept as-is. Any other string is treated as a named route and resolved automatically via the Laravel route() helper.

<x-breadcrumbs :items="[
    ['label' => 'Home', 'link' => 'home'],
    ['label' => 'Users', 'link' => 'users.index'],
    ['label' => 'John Doe'],
]" />

# Icons

<x-breadcrumbs :items="[
    ['label' => 'Home', 'link' => '/', 'icon' => 'home'],
    ['label' => 'Settings', 'link' => '/settings', 'icon' => 'cog-6-tooth'],
    ['label' => 'Profile'],
]" />

# Tooltips

<x-breadcrumbs :items="[
    ['label' => 'Home', 'link' => '/', 'tooltip' => 'Back to homepage'],
    ['label' => 'Users', 'link' => '/users', 'tooltip' => 'View all users'],
    ['label' => 'John Doe'],
]" />

# Sizes

<x-breadcrumbs xs :items="$items" />
<x-breadcrumbs sm :items="$items" />
<x-breadcrumbs :items="$items" /> {{-- md (default) --}}
<x-breadcrumbs lg :items="$items" />

# Separator

The default separator is / . You can customize it with any text:

<x-breadcrumbs separator="»" :items="$items" />
<x-breadcrumbs separator=">" :items="$items" />
<x-breadcrumbs separator="|" :items="$items" />

Or use an icon as separator by prefixing the icon name with icon: :

<x-breadcrumbs separator="icon:chevron-right" :items="$items" />

# Separator Class

Apply additional CSS classes to all separator elements:

<x-breadcrumbs separator-class="text-red-500 font-bold" :items="$items" />

# Slots

Add custom content before or after the breadcrumb trail using the left and right slots:

<x-breadcrumbs :items="$items">
    <x-slot:left>
        <x-icon name="home" class="w-5 h-5 mr-2 text-gray-400" />
    </x-slot:left>
    <x-slot:right>
        <span class="text-xs text-gray-400 ml-2">3 levels</span>
    </x-slot:right>
</x-breadcrumbs>

# Route-Aware Builder

Instead of passing items manually, you can register breadcrumb definitions for named routes and let the component auto-resolve the trail based on the current route. There are two ways to register definitions:

1) Publish a dedicated breadcrumb file (recommended):

php artisan vendor:publish --tag=tallstackui.breadcrumbs

This command will creates a routes/breadcrumbs.php file. Define your breadcrumbs there:

use TallStackUi\Facades\TallStackUi;
use TallStackUi\Support\Breadcrumbs\BreadcrumbTrail;
 
TallStackUi::breadcrumbs()
    ->for('home', fn (BreadcrumbTrail $trail) => $trail
        ->add(label: 'Home', link: '/', icon: 'home')
    )
    ->for('users.index', fn (BreadcrumbTrail $trail) => $trail
        ->parent(route: 'home')
        ->add(label: 'Users', link: 'users.index')
    )
    ->for('users.show', fn (BreadcrumbTrail $trail, User $user) => $trail
        ->parent(route: 'users.index')
        ->add(label: $user->name)
    );

Additionally, you can load any other breadcrumb files in config/tallstackui.php . The paths are relative to base_path() and non-existent files are silently skipped:

// ...
 
'breadcrumbs' => [
    Components\Breadcrumbs\Component::class,
    /*
    |----------------------------------------------------------------------
    | Breadcrumbs Settings
    |----------------------------------------------------------------------
    |
    | files: array of files (relative to base_path()) that register breadcrumb definitions.
    */
    [
        'files' => [
            'routes/breadcrumbs.php',
            'routes/admin-breadcrumbs.php', 
        ],
    ],
],
 
// ...

2) Or you can register breadcrumbs in any service provider's boot method:

use TallStackUi\Facades\TallStackUi;
use Illuminate\Support\ServiceProvider;
use TallStackUi\Support\Breadcrumbs\BreadcrumbTrail;
 
class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        TallStackUi::breadcrumbs()
            ->for(
                'home',
                fn (BreadcrumbTrail $trail) => $trail
                    ->add(label: 'Home', link: '/')
            );
    }
}

Once registered, use the component without passing items to auto-resolve breadcrumbs from the current route. The component will automatically detect the current route and use the breadcrumb definitions to build the trail:

<x-breadcrumbs />

# Parent Chaining

You can create a relationship of children and parent routes by using the parent() method to inherit breadcrumb items from a parent route. Parents are resolved recursively, allowing deep hierarchies:

TallStackUi::breadcrumbs()
    ->for('home', fn (BreadcrumbTrail $trail) => $trail
        ->add(label: 'Home', link: '/')
    )
    ->for('settings.index', fn (BreadcrumbTrail $trail) => $trail
        ->parent(route: 'home')
        ->add(label: 'Settings', link: 'settings.index')
    )
    ->for('settings.profile', fn (BreadcrumbTrail $trail) => $trail
        ->parent(route: 'settings.index')
        ->add(label: 'Profile')
    );

In the code above, note that parent is defined after the base (parent) route is defined, not before. Now when you visiting the page that is associated with the route settings.profile you will see something like this: Home / Settings / Profile

# Route Model Binding

Callback parameters are automatically injected from the current route's model bindings via Laravel's container. Type-hint any route-bound model to receive it:

TallStackUi::breadcrumbs()
    ->for('posts.show', fn (BreadcrumbTrail $trail, Post $post) => $trail
        ->parent(route: 'posts.index')
        ->add(label: $post->title)
    )
    ->for('posts.comments.show', fn (BreadcrumbTrail $trail, Post $post, Comment $comment) => $trail
        ->parent(route: 'posts.show')
        ->add(label: "Comment #{$comment->id}")
    );