laravel-breadcrumbs

Introduction

A simple Laravel-style way to create breadcrumbs.

This project is the official fork of the fantastically original Laravel Breadcrumbs by Dave James Miller and wouldn't have been possible without a bunch of awesome day-one contributors. Thanks, all!

Table of Contents

• Compatibility Chart
• Getting Started
• Defining Breadcrumbs
• Custom Templates
• Outputting Breadcrumbs
• Structured Data
• Route-Bound Breadcrumbs
• Advanced Usage
• FAQ
• Troubleshooting
• Contributing
• License

Compatibility Chart

Laravel	Laravel Breadcrumbs
13.x	10.x
12.x	10.x
11.x	10.x
10.x	10.x
9.x	9.x
8.x	9.x
7.x	8.x
6.x	8.x

For older Laravel versions, reference the original GitHub project. All tags have been mirrored if you prefer referencing this package, but will provide no functional difference.

Getting Started

1. Install

composer require diglactic/laravel-breadcrumbs

2. Define

Create a file called routes/breadcrumbs.php that looks like this:

push('Home', route('home'));
});

// Home > Blog
Breadcrumbs::for('blog', function (BreadcrumbTrail $trail) {
    $trail->parent('home');
    $trail->push('Blog', route('blog'));
});

// Home > Blog > [Category]
Breadcrumbs::for('category', function (BreadcrumbTrail $trail, $category) {
    $trail->parent('blog');
    $trail->push($category->title, route('category', $category));
});

See the Defining Breadcrumbs section for more details.

3. Style

By default, a Bootstrap 5 breadcrumb list will be rendered. To change this, initialize the config file by running this command:

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

Then, open config/breadcrumbs.php and edit this line:

// config/breadcrumbs.php

'view' => 'breadcrumbs::bootstrap5',

The possible values are:

• breadcrumbs::bootstrap5 – Bootstrap 5
• breadcrumbs::bootstrap4 – Bootstrap 4
• breadcrumbs::bulma – Bulma
• breadcrumbs::foundation6 – Foundation 6
• breadcrumbs::json-ld – JSON-LD Structured Data
• breadcrumbs::materialize – Materialize
• breadcrumbs::tailwind – Tailwind CSS
• breadcrumbs::uikit – UIkit
• Or, you can specify the path to a custom view, like partials.breadcrumbs

See the Custom Templates section for more details.

You may also specify a custom view at runtime.

4. Output

Call Breadcrumbs::render() in the view for each page, passing it the name of the breadcrumb to use and any additional parameters:

{{-- resources/views/home.blade.php --}}
{{ Breadcrumbs::render('home') }}

{{-- resources/views/categories/show.blade.php --}}
{{ Breadcrumbs::render('category', $category) }}

See the Outputting Breadcrumbs section for other output options, and see Route-Bound Breadcrumbs for a way to link breadcrumb names to route names automatically.

Defining Breadcrumbs

Breadcrumbs will usually correspond to actions or types of page. For each breadcrumb, you specify a name, the breadcrumb title, and the URL to link it to. Since these are likely to change dynamically, you do this in a closure, and you pass any variables you need into the closure.

The following examples should make it clear:

Static pages

The most simple breadcrumb is probably going to be your homepage, which will look something like this:

push('Home', route('home'));
});

For generating the URL, you can use any of the standard Laravel URL-generation methods, including:

• url('path/to/route') (URL::to())
• secure_url('path/to/route')
• route('routename') or route('routename', 'param') or route('routename', ['param1', 'param2']) (URL::route())
• action('controller@action') (URL::action())
• Or just pass a string URL ('http://www.example.com/')

This example would be rendered like this:

{{ Breadcrumbs::render('home') }}

And result in this output:

Home

Parent links

This is another static page, but with a parent link before it:

parent('home');
    $trail->push('Blog', route('blog'));
});

It works by calling the closure for the home breadcrumb defined above.

It would be rendered like this:

{{ Breadcrumbs::render('blog') }}

And result in this output:

Home / Blog

Note that the default templates do not create a link for the last breadcrumb (the one for the current page), even when a URL is specified. You can override this by creating your own template – see Custom Templates for more details.

Dynamic titles and links

This is a dynamically generated page pulled from the database:

parent('blog');
    $trail->push($post->title, route('post', $post));
});

The $post object (probably an Eloquent Model, but could be anything) would be passed in from the view:

{{ Breadcrumbs::render('post', $post) }}

It results in this output:

Home / Blog / Post Title

You can also chain method calls to $trail. If you're using PHP 7.4 and above with arrow function support, you might prefer the following, more concise, syntax:

Breadcrumbs::for(
    'post',
    fn (BreadcrumbTrail $trail, Post $post) => $trail
        ->parent('blog')
        ->push($post->title, route('post', $post))
);

Nested categories

Finally, if you have nested categories or other special requirements, you can call $trail->push() multiple times:

parent('blog');

    foreach ($category->ancestors as $ancestor) {
        $trail->push($ancestor->title, route('category', $ancestor));
    }

    $trail->push($category->title, route('category', $category));
});

Alternatively, you could make a recursive function such as this:

parent) {
        $trail->parent('category', $category->parent);
    } else {
        $trail->parent('blog');
    }

    $trail->push($category->title, route('category', $category->slug));
});

Both would be rendered like this:

{{ Breadcrumbs::render('category', $category) }}

And result in this:

Home / Blog / Grandparent Category / Parent Category / Category Title

Custom Templates

Create a view

To customize the HTML, create your own view file similar to the following:

 {{-- resources/views/partials/breadcrumbs.blade.php --}}

@unless ($breadcrumbs->isEmpty())
    

        @foreach ($breadcrumbs as $breadcrumb)

            @if (!is_null($breadcrumb->url) && !$loop->last)
                
url }}">{{ $breadcrumb->title }}

            @else
                
{{ $breadcrumb->title }}

            @endif

        @endforeach
    

@endunless

If you want to work off an existing built-in template, run the following command:

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

This will copy all built-in templates into the resources/views/vendor/breadcrumbs/ directory in your project, allowing you to make edits directly.

View data

The view will receive a Collection called $breadcrumbs.

Each breadcrumb is an object with the following keys:

• title – The breadcrumb title
• url – The breadcrumb URL, or null if none was given
• Plus additional keys for each item in $data (see Custom data)

Update the config

Then, update your config file with the custom view name:

// config/breadcrumbs.php

'view' => 'partials.breadcrumbs', // --> resources/views/partials/breadcrumbs.blade.php

Skipping the view

Alternatively, you can skip the custom view and call Breadcrumbs::generate() to get the breadcrumbs collection directly:

@foreach (Breadcrumbs::generate('post', $post) as $breadcrumb)
    {{-- ... --}}
@endforeach

Outputting Breadcrumbs

Call Breadcrumbs::render() in the view for each page, passing it the name of the breadcrumb to use and any additional parameters.

With Blade

{{ Breadcrumbs::render('home') }}

Or with a parameter:

{{ Breadcrumbs::render('category', $category) }}

Structured Data

To render breadcrumbs as JSON-LD structured data (usually for SEO reasons), use Breadcrumbs::view() to render the breadcrumbs::json-ld template in addition to the normal one. For example:

    
        ...
        {{ Breadcrumbs::view('breadcrumbs::json-ld', 'category', $category) }}
        ...
    
    
        ...
        {{ Breadcrumbs::render('category', $category) }}
        ...
    

(Note: If you use Laravel Page Speed you may need to disable the TrimUrls middleware.)

To specify an image, add it to the $data parameter in push():

parent('home');
    $trail->push($post->title, route('post', $post), ['image' => asset($post->image)]);
});

(If you prefer to use Microdata or RDFa you will need to create a custom template.)

Route-Bound Breadcrumbs

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 your routes and avoid this duplication.

Name your routes

Make sure each of your routes has a name.

get('/', 'HomeController@index');

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

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:

push('Home', route('home'));
});

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

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

Breadcrumbs::for('errors.404', function (BreadcrumbTrail $trail) {
    $trail->parent('home');
    $trail->push('Page Not Found');
});

Output breadcrumbs in your layout

Call Breadcrumbs::render() with no parameters in your layout file:

{{