Route-Bound Breadcrumbs

{note} You're browsing the documentation for an old version of laravel-breadcrumbs. Consider upgrading your project to v4. Check your version with the following command:

composer show rawilk/laravel-breadcrumbs

• Introduction
• Name Your Routes
• Name Your Breadcrumbs to Match
• Output Breadcrumbs in your Layout
• Route Binding Exceptions
• Route Model Binding

#Introduction

In normal usage you must call Breadcrumbs::render($name, ...$params) to render the breadcrumbs on every page. If you prefer, you can name your breadcrumbs the same as you name your routes and avoid this duplication.

#Name Your Routes

Make sure each of your routes has a name. For example (routes/web.php):

// Home
Route::get('/', 'HomeController@index')->name('home');

// Home > [Post]
Route::get('/post/{id}', 'PostsController@show')->name('post');

For more details see Named Routes in the Laravel documentation.

#Name Your Breadcrumbs to Match

For each route, create a breadcrumb with the same name and parameters. For example (routes/breadcrumbs.php):

// Home
Breadcrumbs::for('home', fn (Generator $trail) => $trail->push('Home', route('home')));

// Home > [Post]
Breadcrumbs::for('post', function (Generator $trail, $id) {
    $post = Post::findOrFail($id);
    $trail->parent('home')->push($post->title, route('post', $post));
});

To add breadcrumbs to a custom 404 Not Found page, use the name errors.404:

// Error 404
Breadcrumbs::for('errors.404', fn (Generator $trail) => $trail->parent('home')->push('Page Not Found'));

#Output Breadcrumbs in your Layout

Call Breadcrumbs::render() with no parameters in your layout file (e.g. resources/views/app.blade.php):

{!! Breadcrumbs::render() !!}

This will automatically output breadcrumbs corresponding to the current route. The same applies to Breadcrumbs::generate():

$breadcrumbs = Breadcrumbs::generate();

And for Breadcrumbs::view():

{!! Breadcrumbs::view('breadcrumbs::json-ld') !!}

#Route Binding Exceptions

If you try to render a breadcrumb that doesn't exist, the package will throw a BreadcrumbsNotRegistered Exception to remind you to create one. You can disable this (e.g. if you have some pages with no breadcrumbs) in the config/breadcrumbs.php file:

'exceptions' => [
    ...
    'missing_route_bound_breadcrumb' => false,
],

Similarly, to prevent it from throwing an UnnamedRoute Exception if the current route doesn't have a name, set this value:

'exceptions' => [
    'unnamed_route' => false,
    ...
],

#Route Model Binding

Laravel Breadcrumbs uses the same binding as the controller. For example:

// routes/web.php
Route::get('/post/{post}', 'PostsController@show')->name('post');

// app/Http/Controllers/PostsController.php
use App\Post;

class PostsController extends Controller
{
    public function show(Post $post) // <-- Implicit model binding happens here
    {
        return view('posts.show', compact('post'));
    }
}

// routes/breadcrumbs.php
Breadcrumbs::for('post', function (Generator $trail, $post) { // <-- The same Post model is injected here
    $trail->parent('home')
        ->push($post->title, route('post', $post));
});

Using route model binding makes your code less verbose and more efficient by only loading the post from the database once. You can optionally type-hint the $post parameter for clarity if you want to.

For more details see Route Model Binding in the Laravel documentation.