README

This package automatically shares breadcrumbs as Inertia props in a standardized way, with support for multiple breadcrumb packages.

Installation

You can install the package via composer:

composer require robertboes/inertia-breadcrumbs

You can publish the config file with:

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

Next step is to install one of the following packages to manage your breadcrumbs, or use the built-in closure collector:

• diglactic/laravel-breadcrumbs
• tabuna/breadcrumbs
• glhd/gretel
• Built-in closure collector (no additional package required)

Note

Until you install one of these packages or configure a different collector, requests through the web middleware group will throw PackageNotInstalledException, because the default collector requires diglactic/laravel-breadcrumbs.

Configure your breadcrumbs as explained by the package you've chosen.

Update your config/inertia-breadcrumbs.php configuration to use the correct collector:

// diglactic/laravel-breadcrumbs
use RobertBoes\InertiaBreadcrumbs\Collectors\DiglacticBreadcrumbsCollector;

return [
    'collector' => DiglacticBreadcrumbsCollector::class,
];

// tabuna/breadcrumbs
use RobertBoes\InertiaBreadcrumbs\Collectors\TabunaBreadcrumbsCollector;

return [
    'collector' => TabunaBreadcrumbsCollector::class,
];

// glhd/gretel
use RobertBoes\InertiaBreadcrumbs\Collectors\GretelBreadcrumbsCollector;

return [
    'collector' => GretelBreadcrumbsCollector::class,
];

// Built-in closure collector
use RobertBoes\InertiaBreadcrumbs\Collectors\ClosureBreadcrumbsCollector;

return [
    'collector' => ClosureBreadcrumbsCollector::class,
];

Usage

No matter which third party package you're using, this package will always share breadcrumbs to Inertia in the following format:

[
    {
        "title": "Dashboard",
        "url": "http://localhost/dashboard"
    },
    {
        "title": "Profile",
        "url": "http://localhost/dashboard/profile",
        "current": true
    },
    {
        "title": "Breadcrumb without URL"
    }
]

Note

Note that due to package differences, URLs are always present when using glhd/gretel, but are otherwise optional.

An example to render your breadcrumbs in Vue 3 could look like the following:

<template>
    <nav v-if="$page.props.breadcrumbs">
        <ol>
            <li v-for="crumb in $page.props.breadcrumbs" :key="crumb.title">
                <a
                    v-if="crumb.url"
                    :href="crumb.url"
                    :class="{ 'border-b border-blue-400': crumb.current }"
                >{{ crumb.title }}</a>
                <span v-else>{{ crumb.title }}</span>
            </li>
        </ol>
    </nav>
</template>

Using the closure collector

If you don't want to install a third-party breadcrumb package, you can use the built-in closure collector. This allows you to define breadcrumbs directly using closures, either in a service provider or in your controllers.

Update your config/inertia-breadcrumbs.php to use the ClosureBreadcrumbsCollector:

use RobertBoes\InertiaBreadcrumbs\Collectors\ClosureBreadcrumbsCollector;

return [
    'collector' => ClosureBreadcrumbsCollector::class,
];

Then define your breadcrumbs by route name. You can do this in a service provider:

<?php

namespace App\Providers;

use RobertBoes\InertiaBreadcrumbs\Breadcrumb;
use RobertBoes\InertiaBreadcrumbs\InertiaBreadcrumbs;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        $breadcrumbs = app(InertiaBreadcrumbs::class);

        $breadcrumbs->for('users.index', fn () => [
            Breadcrumb::make('Users', route('users.index')),
        ]);

        $breadcrumbs->for('users.show', fn (User $user) => [
            Breadcrumb::make('Users', route('users.index')),
            Breadcrumb::make($user->name, route('users.show', $user)),
        ]);
    }
}

Or directly in your controllers. When called without a route name, the current route name is automatically inferred from the request:

<?php

namespace App\Http\Controllers;

use App\Models\User;
use RobertBoes\InertiaBreadcrumbs\Breadcrumb;
use RobertBoes\InertiaBreadcrumbs\InertiaBreadcrumbs;

class UserController extends Controller
{
    public function show(User $user, InertiaBreadcrumbs $breadcrumbs)
    {
        $breadcrumbs->for(fn (User $user) => [
            Breadcrumb::make('Users', route('users.index')),
            Breadcrumb::make($user->name, route('users.show', $user)),
        ]);

        return inertia('Users/Show', ['user' => $user]);
    }
}

Route parameters are automatically passed to the closure based on the current route. The current property is automatically determined by comparing the breadcrumb URL with the current request URL, but you can also set it explicitly via Breadcrumb::make('Title', $url, current: true).

Note

When using the shorthand (passing a closure as the first argument) on a named route, the route name is automatically inferred from the request. On unnamed routes, the breadcrumbs are stored as pending and resolved for the current request only. The service provider approach always requires an explicit route name.

Share strategy

Controls how breadcrumbs are shared with Inertia. You can configure this in config/inertia-breadcrumbs.php:

use RobertBoes\InertiaBreadcrumbs\ShareStrategy;

return [
    'share' => ShareStrategy::Default,
];

• ShareStrategy::Default — Standard shared prop, excluded during partial reloads unless explicitly requested
• ShareStrategy::Always — Always included in the response, even during partial reloads
• ShareStrategy::Deferred — Excluded from the initial page load, automatically fetched after the page renders

You can also use string values ('default', 'always', 'deferred') instead of the enum.

Using a classifier

A classifier is used to determine when breadcrumbs should be shared as Inertia props. By default all breadcrumbs are shared, but this package is shipped with the IgnoreSingleBreadcrumbs classifier, which simply discards a breadcrumb collection containing only one route.

To write your own classifier you'll have to implement RobertBoes\InertiaBreadcrumbs\Classifier\ClassifierContract and update the inertia-breadcrumbs.classifier config, for example:

<?php

namespace App\Support;

use Illuminate\Support\Str;
use RobertBoes\InertiaBreadcrumbs\Classifier\ClassifierContract;
use RobertBoes\InertiaBreadcrumbs\BreadcrumbCollection;

class IgnoreAdminBreadcrumbs implements ClassifierContract
{
    public function shouldShareBreadcrumbs(BreadcrumbCollection $collection): bool
    {
        return ! Str::startsWith($collection->first()?->url() ?? '', url('/admin'));
    }
}

Serializing breadcrumbs

In some cases you might not like the default way breadcrumbs are serialized. To modify the way the breadcrumbs are being sent to the frontend you can register a serialize callback in the boot method of a service provider:

<?php

namespace App\Providers;

use RobertBoes\InertiaBreadcrumbs\Breadcrumb;
use RobertBoes\InertiaBreadcrumbs\InertiaBreadcrumbs;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        app(InertiaBreadcrumbs::class)->serializeUsing(fn (Breadcrumb $breadcrumb) => [
            'name' => $breadcrumb->title(),
            'href' => $breadcrumb->url(),
            'active' => $breadcrumb->current(),
            'data' => $breadcrumb->data(),
        ]);
    }
}

Including the query string when determining the current URL

By default, the query string will be ignored when determining the current url, meaning a breadcrumb defined for /users/{id} will match both /users/1 and /users/1?foo=bar. To change this behaviour and include the query string (meaning /users/1?foo=bar will not be seen as the current page), change ignore_query to false in the config/inertia-breadcrumbs.php file.

Notes on using glhd/gretel

glhd/gretel shares the breadcrumbs automatically if it detects Inertia is installed and shares the props with the same key (breadcrumbs). If you want to use this package with gretel you should disable their automatic sharing by updating the config:

// config/gretel.php

return [
    'packages' => [
        'inertiajs/inertia-laravel' => false,
    ],
];

Testing

composer test

Upgrading

For notable changes see UPGRADING.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Robert Boes
• All Contributors

License

The MIT License (MIT). Please see License File for more information.