PHPackages                             glhd/gretel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. glhd/gretel

ActiveLibrary

glhd/gretel
===========

1.10.0(1mo ago)270305.7k↑20.7%22[2 PRs](https://github.com/glhd/gretel/pulls)4MITPHPCI passing

Since Sep 27Pushed 3mo ago2 watchersCompare

[ Source](https://github.com/glhd/gretel)[ Packagist](https://packagist.org/packages/glhd/gretel)[ RSS](/packages/glhd-gretel/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (16)Versions (21)Used By (4)

[![Gretel from the story 'Hansel and Gretel' holding bread behind her back](gretel.png)](gretel.png)

 [ ![Build Status](https://github.com/glhd/gretel/workflows/PHPUnit/badge.svg) ](https://github.com/glhd/gretel/actions) [ ![Coverage Status](https://camo.githubusercontent.com/e263707007a748e109bd7e4dc04fae42ef694c5ecf844f170dfad356660d5e6c/68747470733a2f2f6170692e636f6465636c696d6174652e636f6d2f76312f6261646765732f66353937613665386439663936386135356630332f746573745f636f766572616765) ](https://codeclimate.com/github/glhd/gretel/test_coverage) [ ![Latest Stable Release](https://camo.githubusercontent.com/dc8ca0e323d8f787eefe08dfd14c5722816229b91478feef2a5b25fbb984ba73/68747470733a2f2f706f7365722e707567782e6f72672f676c68642f67726574656c2f762f737461626c65) ](https://packagist.org/packages/glhd/gretel) [ ![MIT Licensed](https://camo.githubusercontent.com/4b3e9e1618315c9cc3a4e33538bc55a79a1f9ac95ffb38f0a46d51e0e3c12379/68747470733a2f2f706f7365722e707567782e6f72672f676c68642f67726574656c2f6c6963656e7365) ](./LICENSE) [ ![Follow @inxilpro on Twitter](https://camo.githubusercontent.com/e6d0a3893c652423c3a7c6aa648ca6e98a3b06899551e17a2fe5b33528244dcb/68747470733a2f2f696d672e736869656c64732e696f2f747769747465722f666f6c6c6f772f696e78696c70726f3f7374796c653d736f6369616c) ](https://twitter.com/inxilpro)

Gretel
======

[](#gretel)

> Laravel breadcrumbs right out of a fairy tale.

Gretel is a Laravel package for adding route-based breadcrumbs to your application.

- [Defining Breadcrumbs](#defining-breadcrumbs)
- [Displaying Breadcrumbs](#displaying-breadcrumbs)
- [Using Gretel With Your CSS Framework of Choice](#supported-frameworks)
- [Using a Custom Template](#custom-breadcrumb-view) (while maintaining accessibility)
- [Caching Breadcrumbs](#caching-breadcrumbs) (required if using `route:cache`)
- [Handling Errors](#handling-errors)
- [Integration With Third Party Packages](#integration-with-third-party-packages) (Inertia.js)

Installation
------------

[](#installation)

```
composer require glhd/gretel
```

Usage
-----

[](#usage)

### Defining Breadcrumbs

[](#defining-breadcrumbs)

Gretel adds a new Route macro that you can use when defining your routes:

#### Single Breadcrumb

[](#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');
```

[![Homepage Example](https://user-images.githubusercontent.com/21592/134791634-186fd0a2-4262-4778-96d1-713e10931ae9.png)](https://user-images.githubusercontent.com/21592/134791634-186fd0a2-4262-4778-96d1-713e10931ae9.png)

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');
```

[![Dashboard Example](https://user-images.githubusercontent.com/21592/134791636-d97d767f-6506-41c6-895d-611840e40fa9.png)](https://user-images.githubusercontent.com/21592/134791636-d97d767f-6506-41c6-895d-611840e40fa9.png)

#### Nested Breadcrumb

[](#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');
```

[![Nested Route Example](https://user-images.githubusercontent.com/21592/134791637-2a10a46e-250b-4738-b8fa-68169fc830dd.png)](https://user-images.githubusercontent.com/21592/134791637-2a10a46e-250b-4738-b8fa-68169fc830dd.png)

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](#shallow-nested-routes)).

##### Parent Shorthand

[](#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

[](#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);
```

[![Shallow Nested Example](https://user-images.githubusercontent.com/21592/134791638-fbb87040-e27f-4749-9175-0f5dce995924.png)](https://user-images.githubusercontent.com/21592/134791638-fbb87040-e27f-4749-9175-0f5dce995924.png)

#### Resource Routes

[](#resource-routes)

You can also define breadcrumbs for resource controllers. The `index()`, `create()`, `show()`, and `edit()` methods behave exactly like the regular breadcrumb helper except that they automatically set up the parent for you if you don’t provide one.

```
Route::resource('users', UserController::class)
  ->breadcrumbs(function(ResourceBreadcrumbs $breadcrumbs) {
    $breadcrumbs
      ->index('Users')
      ->create('New User')
      ->show(fn(User $user) => $user->name)
      ->edit('Edit');
  });
```

If you prefer, you can also use an array syntax for simple resource routes:

```
Route::resource('users', UserController::class)
  ->breadcrumbs([
    'index' => 'Users',
    'create' => 'New User',
    'show' => fn(User $user) => $user->name,
    'edit' => 'Edit',
  ]);
```

#### Vendor Routes

[](#vendor-routes)

Sometimes you want to register breadcrumbs for routes that are defined in 3rd-party packages. In this case, you can use the `Gretel` facade directly. The API is exactly the same as the `Route::breadcrumb()` method, except that you must pass the route name as the first parameter:

```
Gretel::breadcrumb(
  'teams.show', // Route name
  fn(Team $team) => $team->name, // Title callback
  'profile.show', // Parent
);
```

### Displaying Breadcrumbs

[](#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 `` tag#### Supported Frameworks

[](#supported-frameworks)

Gretel supports most common CSS frameworks. We've taken the CSS framework's documented markup and added additional `aria-` tags where appropriate for better accessibility. Currently supported frameworks:

##### [Tailwind](https://tailwindcss.com/) use `"tailwind"` (default)

[](#tailwind-use-tailwind-default)

[![Tailwind theme](https://user-images.githubusercontent.com/21592/135018688-4a183ec0-bfc9-4168-80c8-6b7cd037de4d.png)](https://user-images.githubusercontent.com/21592/135018688-4a183ec0-bfc9-4168-80c8-6b7cd037de4d.png)

##### [Materialize](https://materializecss.com/breadcrumbs.html) use `"materialize"`

[](#materialize-use-materialize)

[![Materialize theme](https://user-images.githubusercontent.com/21592/135018804-88de948a-f69d-4960-ae0a-5d51cfed02dc.png)](https://user-images.githubusercontent.com/21592/135018804-88de948a-f69d-4960-ae0a-5d51cfed02dc.png)

##### [Bootstrap 5](https://getbootstrap.com/docs/5.0/components/breadcrumb/) use `"bootstrap5"`

[](#bootstrap-5-use-bootstrap5)

[![Bootstrap 5 theme](https://user-images.githubusercontent.com/21592/135088728-cd1ccec9-12c1-4153-a9a2-757a3d6d426e.png)](https://user-images.githubusercontent.com/21592/135088728-cd1ccec9-12c1-4153-a9a2-757a3d6d426e.png)

##### [Bulma](https://bulma.io/documentation/components/breadcrumb/) use `"bulma"`

[](#bulma-use-bulma)

[![Bulma theme](https://user-images.githubusercontent.com/21592/135089118-7be25e4a-1e68-4c89-ac5b-8307528e3fa0.png)](https://user-images.githubusercontent.com/21592/135089118-7be25e4a-1e68-4c89-ac5b-8307528e3fa0.png)

##### [Semantic UI](https://semantic-ui.com/collections/breadcrumb.html) use `"semantic-ui"`

[](#semantic-ui-use-semantic-ui)

[![Semantic UI theme](https://user-images.githubusercontent.com/21592/135089752-9dd36b92-e4bf-458e-944e-a2a0c8da82f3.png)](https://user-images.githubusercontent.com/21592/135089752-9dd36b92-e4bf-458e-944e-a2a0c8da82f3.png)

##### [Primer](https://primer.style/css/components/breadcrumb) use `"primer"`

[](#primer-use-primer)

[![Primer theme](https://user-images.githubusercontent.com/21592/135090274-cfea4c55-3d30-4343-ba17-5784a1e6bfc3.png)](https://user-images.githubusercontent.com/21592/135090274-cfea4c55-3d30-4343-ba17-5784a1e6bfc3.png)

##### [Foundation 6](https://get.foundation/sites/docs/breadcrumbs.html) use `"foundation6"`

[](#foundation-6-use-foundation6)

[![Foundation 6 theme](https://user-images.githubusercontent.com/21592/135090758-ce9d1b73-2cf7-42df-9717-d4ca306c5019.png)](https://user-images.githubusercontent.com/21592/135090758-ce9d1b73-2cf7-42df-9717-d4ca306c5019.png)

##### [UIKit](https://getuikit.com/docs/breadcrumb) use `"uikit"`

[](#uikit-use-uikit)

[![UIKit theme](https://user-images.githubusercontent.com/21592/135090949-cb448dac-42ff-4cac-9446-3d0939d2ec2e.png)](https://user-images.githubusercontent.com/21592/135090949-cb448dac-42ff-4cac-9446-3d0939d2ec2e.png)

##### Older Frameworks

[](#older-frameworks)

Older versions of some frameworks are also available:

- [Bootstrap 3](https://getbootstrap.com/docs/3.3/components/#breadcrumbs) use `"bootstrap3"`
- [Bootstrap 4](https://getbootstrap.com/docs/4.6/components/breadcrumb/) use `"bootstrap4"`
- [Foundation 5](https://get.foundation/sites/docs-v5/components/breadcrumbs.html) use `"foundation5"`

You'll typically want to include the `` tag somewhere in your application layout (maybe twice if you're using JSON-LD):

#### `layouts/app.blade.php`:

[](#layoutsappbladephp)

```
>

    {{ $title }}

    ...

```

#### Custom Breadcrumb View

[](#custom-breadcrumb-view)

You can render a custom view either by publishing the `gretel.php` config file via `php artisan vendor:publish` or by passing a `view` attribute to the Blade component:

```

```

#### Using Breadcrumbs in Some Other Way

[](#using-breadcrumbs-in-some-other-way)

If you need to use the breadcrumbs in some other way—maybe for rending via a client-side framework that Gretel doesn’t already integrate with—you can always just get the current breadcrumbs as a `Collection` or `array` off the route:

```
Route::breadcrumbs()->toCollection();  // Collection of `Breadcrumb` objects
Route::breadcrumbs()->toArray();       // Array of `Breadcrumb` objects
Route::breadcrumbs()->jsonSerialize(); // Array of breadcrumb arrays (title, url, is_current_page)
Route::breadcrumbs()->toJson();        // JSON string of breadcrumbs matching jsonSerialize
```

For example, our [Inertia.js integration](#integration-with-third-party-packages) could easily be implemented as:

```
Inertia::share('breadcrumbs', function(Request $request) {
    return $request->route()->breadcrumbs()->jsonSerialize();
});
```

##### Accessibility

[](#accessibility)

If you choose to render your own view, please be sure to follow the current [WAI-ARIA accessibility best practices](https://www.w3.org/TR/wai-aria-practices-1.1/examples/breadcrumb/index.html). Gretel provides some helpers to make this easier:

```
@unless ($breadcrumbs->isEmpty())

      @foreach ($breadcrumbs as $breadcrumb)

              {{ $breadcrumb->title }}

      @endforeach

@endunless
```

### Caching Breadcrumbs

[](#caching-breadcrumbs)

Because Gretel breadcrumbs are registered alongside your routes, you need to cache your breadcrumbs if you cache your routes. You can do so with the two commands:

```
# Cache breadcrumbs
php artisan breadcrumbs:cache

# Clear cached breadcrumbs
php artisan breadcrumbs:clear
```

Please note that you must cache your breadcrumbs **before you cache your routes**.

### Handling Errors

[](#handling-errors)

Sometimes you'll mis-configure a breadcrumb or forget to define one. You can register handlers on the `Gretel` facade to handle these cases:

```
// Log or report a missing breadcrumb (will always receive a MissingBreadcrumbException instance)
Gretel::handleMissingBreadcrumbs(function(MissingBreadcrumbException $exception) {
  Log::warning($exception->getMessage());
});

// Throw an exception locally if there's a missing breadcrumb
Gretel::throwOnMissingBreadcrumbs(! App::environment('production'));

// Log or report a mis-configured breadcrumb (i.e. a parent route that doesn't exist).
// This handler will pick up any other exception that is triggered while trying to configure
// or render your breadcrumbs, so the type is unknown.
Gretel::handleMisconfiguredBreadcrumbs(function(Throwable $exception) {
  Log::warning($exception->getMessage());
});

// Throw an exception locally if there's a mis-configured breadcrumb
Gretel::throwOnMisconfiguredBreadcrumbs(! App::environment('production'));
```

### Integration With Third Party Packages

[](#integration-with-third-party-packages)

Gretel automatically [shares your breadcrumbs with Inertia.js](https://inertiajs.com/shared-data)if you have that package installed. You don't need to do anything to enable this integration. (If you do not want this behavior for some reason, you can disable it by publishing the Gretel config.)

Your breadcrumbs will be available in your client code as `breadcrumbs` and look something like:

```
const breadcrumbs = [
  {
    title: 'Home',
    url: 'https://www.yourapp.com',
    is_current_page: false,
  }, {
    title: 'Users',
    url: 'https://www.yourapp.com/users',
    is_current_page: false,
  }, {
    title: 'Add a User',
    url: 'https://www.yourapp.com/users/create',
    is_current_page: true,
  }
];
```

You can then render the breadcrumbs in the client however you see fit. Be sure to review the [custom breadcrumbs](#custom-breadcrumb-view) section for information about how to ensure that your client-side breadcrumbs are fully accessible.

###  Health Score

58

—

FairBetter than 98% of packages

Maintenance84

Actively maintained with recent releases

Popularity54

Moderate usage in the ecosystem

Community22

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 98.2% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~96 days

Recently: every ~185 days

Total

18

Last Release

56d ago

Major Versions

0.1.1 → 1.0.02021-09-28

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/21592?v=4)[Chris Morrell](/maintainers/inxilpro)[@inxilpro](https://github.com/inxilpro)

---

Top Contributors

[![inxilpro](https://avatars.githubusercontent.com/u/21592?v=4)](https://github.com/inxilpro "inxilpro (111 commits)")[![onlime](https://avatars.githubusercontent.com/u/2759561?v=4)](https://github.com/onlime "onlime (1 commits)")[![Spice-King](https://avatars.githubusercontent.com/u/590498?v=4)](https://github.com/Spice-King "Spice-King (1 commits)")

---

Tags

laravelbreadcrumbs

###  Code Quality

TestsPHPUnit

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/glhd-gretel/health.svg)

```
[![Health](https://phpackages.com/badges/glhd-gretel/health.svg)](https://phpackages.com/packages/glhd-gretel)
```

###  Alternatives

[laravel/cashier

Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services.

2.5k25.9M107](/packages/laravel-cashier)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9682.1M97](/packages/roots-acorn)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k12.1M99](/packages/laravel-pulse)[laravel-doctrine/orm

An integration library for Laravel and Doctrine ORM

8425.3M87](/packages/laravel-doctrine-orm)[psalm/plugin-laravel

Psalm plugin for Laravel

3274.9M308](/packages/psalm-plugin-laravel)[laravel/folio

Page based routing for Laravel.

608453.9k27](/packages/laravel-folio)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)