Laravel Breadcrumbs

A simple breadcrumbs package for Laravel, with support for Blade and Inertia.js.

// In your controller
crumbs('Posts', '/posts')->add('Show Post', route('posts.show', $post));

<!-- In your Blade view -->
@crumbs

// In your Inertia component
<Breadcrumbs items={breadcrumbs} />

Installation

composer require vixen/laravel-breadcrumbs

The service provider is auto-discovered. To publish the config and views:

php artisan vendor:publish --tag="breadcrumbs-config"
php artisan vendor:publish --tag="breadcrumbs-views"

Quick Start

Add breadcrumbs from your controller or routes file, then render them in your view.

Adding Breadcrumbs

From a controller:

public function show(Post $post)
{
    crumbs('Posts', '/posts')->add($post->title, route('posts.show', $post));
}

From your routes file:

Route::get('posts', [PostController::class, 'index'])->crumbs(function (Breadcrumbs $crumbs) {
    $crumbs->add('Posts', '/posts');
});

Rendering

In Blade, use the @crumbs directive or call render() directly:

@crumbs

{{-- or with a custom view --}}
@crumbs(breadcrumbs::custom-view)

For Inertia.js, the breadcrumbs are available as a JSON-serializable array via crumbs()->toArray() or crumbs()->toJson().

Usage

Notations

There are three interchangeable ways to interact with breadcrumbs:

Helper function (recommended):

crumbs('Home', '/')->add('About', '/about');

Facade:

use Vixen\Breadcrumbs\Facades\Crumbs;

Crumbs::add('Home', '/');

Dependency injection:

use Vixen\Breadcrumbs\Breadcrumbs;

public function index(Breadcrumbs $crumbs)
{
    $crumbs->add('Home', '/');
}

Options Array

Instead of separate arguments, you can pass an associative array:

crumbs([
    'title' => 'Posts',
    'path' => '/posts',
    'extra' => ['icon' => 'newspaper'],
]);

Multi-Item Positions

A position in the trail can hold multiple items by passing a sequential array. This is useful for rendering a dropdown selector instead of a single link:

// Home > [Electronics | Clothing | Books] > Product Name
crumbs('Home', '/')
    ->add([
        ['title' => 'Electronics', 'path' => '/categories/electronics'],
        ['title' => 'Clothing', 'path' => '/categories/clothing'],
        ['title' => 'Books', 'path' => '/categories/books'],
    ])
    ->add($product->name, route('products.show', $product));

When iterating, a multi-item position is an array of Breadcrumb objects rather than a single one. Each item independently tracks its own active state.

Custom Views

Publish the views and edit them, or create your own. The default view (breadcrumbs::plain):

<nav aria-label="Breadcrumb">
    <ol role="list" style="display: flex; align-items: center; gap: 1rem">
        @foreach ($breadcrumbs as $breadcrumb)
            @if (!$loop->first)
                <li>/</li>
            @endif

            @if ($breadcrumb->active)
                <li>{{ $breadcrumb->title }}</li>
            @else
                <li>
                    <a href="{{ $breadcrumb->path }}">
                        {{ $breadcrumb->title }}
                    </a>
                </li>
            @endif
        @endforeach
    </ol>
</nav>

You can specify a different view globally in config/breadcrumbs.php or per-render:

crumbs()->render('breadcrumbs::custom-view')

API

Breadcrumbs::add(string|array $title, ?string $path = null, array $extra = [])

| Parameter | Type | Description | |-----------|-----------------|---------------------------------------------------------------------| | $title | string\|array | The breadcrumb label, an options array, or a list of options arrays | | $path | ?string | A URL string. null means no link. | | $extra | array | Arbitrary extra data attached to the breadcrumb. |

When $title is an associative array, it is treated as a single breadcrumb with keys title, path (optional), and extra (optional).

When $title is a sequential array, each element is an options array and the items are grouped at a single position in the trail.

crumbs(string|array|callable|null $title = null, ?string $path = null, array $extra = [])

Same as Breadcrumbs::add(), but also accepts a callable and returns the Breadcrumbs instance. Called without arguments, it simply returns the instance.

Breadcrumb Properties

| Property | Type | Description | |----------|-----------|---------------------------------------------| | title | string | The breadcrumb label. | | path | ?string | The URL, or null if none was provided. | | active | bool | true when path matches the current URL. | | extra | array | Arbitrary extra data. |

Changelog

See CHANGELOG for all changes.

Contributing

See CONTRIBUTING for details.

Credits

• Alex Torscho
• All Contributors

License

MIT. See LICENSE for details.