Gretel
Laravel breadcrumbs right out of a fairy tale.
Gretel is a Laravel package for adding route-based breadcrumbs to your application.
- Defining Breadcrumbs
- Displaying Breadcrumbs
- Using Gretel With Your CSS Framework of Choice
- Using a Custom Template (while maintaining accessibility)
- Caching Breadcrumbs (required if using
route:cache) - Handling Errors
Installation
composer require glhd/gretel
Usage
Defining Breadcrumbs
Gretel adds a new Route macro that you can use when defining your routes:
Single Breadcrumb
In the simplest case, chain the breadcrumb() function onto your existing route to define a breadcrumb:
Route::get('/', HomeController::class)
->name('home')
->breadcrumb('Home');
If you need to dynamically control the title, pass in a closure instead:
Route::get('/dashboard', DashboardController::class)
->name('dashboard')
->breadcrumb(fn() => Auth::user()->name.'’s dashboard');
Nested Breadcrumb
Breadcrumbs aren't very useful unless you string them together. Gretel handles nested breadcrumbs by pointing to a previously-defined parent breadcrumb:
Route::get('/users', [UserController::class, 'index'])
->name('users.index')
->breadcrumb('Users');
Route::get('/users/{user}', [UserController::class, 'show'])
->name('users.show')
->breadcrumb(fn(User $user) => $user->name, 'users.index');
Route::get('/users/{user}/edit', [UserController::class, 'edit'])
->name('users.edit')
->breadcrumb('Edit', 'users.show');
Here, you can see that our users.show route references users.index as its parent. This way, when you render breadcrumbs for users.show it will also show the breadcrumb for users.index.
Gretel assumes that the parameters in nested routes can be safely used for their parent routes. In this example, users.edit will render the users.show breadcrumb using the User value that was resolved for the edit action. In the vast majority of cases, this is exactly what you want. If not, you can override this behavior (see below).
Parent Shorthand
Often, a child route will reference a parent with the same name prefix. In our above example, users.show references users.index and users.edit references users.show. In this case, you can use the parent shorthand:
Route::get('/admin/users/{user}/notes/create', [NotesController::class, 'create'])
->name('admin.users.notes.create')
->breadcrumb('Add Note', '.index'); // shorthand for "admin.users.notes.index"
This is particularly useful for large apps that have many deeply nested routes.
Shallow Nested Routes
If your nested routes do not contain the route parameters necessary for the parent route, you will need to provide the values to Gretel. You can do this using a third callback:
Route::get('/companies/{company}', [CompanyController::class, 'show'])
->name('companies.show')
->breadcrumb(fn(Company $company) => $company->name);
Route::get('/users/{user}', [UserController::class, 'show'])
->name('users.show')
->breadcrumb(fn(User $user) => $user->name, 'companies.show', fn(User $user) => $user->company);
Displaying Breadcrumbs
You can display the breadcrumbs for the current route with the
Blade component. The Blade component accepts a few optional attributes:
| Attribute | |
|---|---|
framework |
Render to match a UI framework ("tailwind" by default) |
view |
Render a custom view (supersedes the framework attribute) |
jsonld |
Render as a JSON-LD |
13 Mar 2, 2022
75 Dec 7, 2022
16 Feb 18, 2022
2 Sep 13, 2022
1 Jun 21, 2022
108 Dec 11, 2022
2 Aug 23, 2022
686 Dec 28, 2022
931 Dec 24, 2022
79 Dec 29, 2022
230 Dec 27, 2022
4 May 12, 2022
1.7k Jan 5, 2023
16 Jul 7, 2022
441 Jan 5, 2023
5 Nov 17, 2022
2 Jul 27, 2022
109 Dec 26, 2022