README

A simple and flexible breadcrumb package for Laravel 12+ applications that provides an easy way to manage and display breadcrumb navigation using FluxUI components.

Features

Simple and intuitive breadcrumb definition
Support for nested breadcrumbs with parent relationships
Automatic breadcrumb generation from current route
Built-in FluxUI component integration
Special Dashboard icon support
Artisan command for generating breadcrumb definitions
Full Pest test coverage
Laravel 12+ only support

Requirements

PHP 8.2+
Laravel 12+
FluxUI (Livewire Flux)

Installation

You can install the package via composer:

composer require act-training/laravel-breadcrumbs

The package will automatically register its service provider.

Note: This package requires FluxUI to be installed and configured in your Laravel application.

You can publish the config file with:

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

You can publish the views with:

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

Usage

Defining Breadcrumbs

Create a routes/breadcrumbs.php file to define your breadcrumbs:

<?php

use ActTraining\LaravelBreadcrumbs\Facades\Breadcrumbs;

// Dashboard
Breadcrumbs::define('dashboard', function ($trail) {
    $trail->push('Dashboard', route('dashboard'));
});

// Users Index
Breadcrumbs::define('users.index', function ($trail) {
    $trail->parent('dashboard');
    $trail->push('Users', route('users.index'));
});

// User Show
Breadcrumbs::define('users.show', function ($trail, $user) {
    $trail->parent('users.index');
    $trail->push($user->name, route('users.show', $user));
});

Displaying Breadcrumbs

In your Blade templates, use the breadcrumbs component:

<!-- Automatically generate from current route -->
<x-breadcrumbs />

<!-- Or specify a specific route -->
<x-breadcrumbs route="users.show" :params="[$user]" />

Artisan Command

Generate breadcrumb definitions using the Artisan command:

php artisan make:breadcrumb users.edit --parent=users.show --title="Edit User"

Manual Usage

You can also generate breadcrumbs manually:

use ActTraining\LaravelBreadcrumbs\Facades\Breadcrumbs;

// Generate breadcrumbs for a specific route
$breadcrumbs = Breadcrumbs::generate('users.show', $user);

// Generate breadcrumbs from current route
$breadcrumbs = Breadcrumbs::generateFromRoute();

// Check if breadcrumb exists
if (Breadcrumbs::exists('users.show')) {
    // ...
}

Configuration

The package comes with a configuration file that allows you to customize various aspects:

return [
    // Path to breadcrumb definitions file (defaults to routes/breadcrumbs.php if null)
    'definitions_file' => base_path('routes/breadcrumbs.php'),

    // Default view for rendering breadcrumbs
    'view' => 'breadcrumbs::breadcrumbs',

    // Hide breadcrumbs when only one item exists
    'skip_single_item' => true,

    // Separator character between breadcrumb items
    'separator' => '/',

    // CSS classes for breadcrumb elements
    'classes' => [
        'wrapper' => 'breadcrumbs',
        'list' => 'breadcrumb-list',
        'item' => 'breadcrumb-item',
        'link' => 'breadcrumb-link',
        'active' => 'breadcrumb-active',
        'separator' => 'breadcrumb-separator',
    ],

    // The route name that represents home (e.g., 'dashboard', 'home', 'index')
    'home_route' => 'dashboard',

    // How to display the home breadcrumb: 'icon', 'text', or 'both'
    'home_display' => 'icon',

    // The FluxUI icon to use for home (e.g., 'house', 'home', 'squares-2x2')
    'home_icon' => 'house',
];

Customizing Views

You can customize the breadcrumb HTML by publishing the views and modifying them:

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

The default view will be published to resources/views/vendor/breadcrumbs/breadcrumbs.blade.php.

FluxUI Integration

The package uses FluxUI components for rendering breadcrumbs:

<flux:breadcrumbs> for the main breadcrumb container
<flux:breadcrumbs.item> for individual breadcrumb items
<flux:icon icon="house"> for the special Dashboard icon

The default styling includes:

Orange accent color for Dashboard items
Responsive text sizing
Dark mode support
Hover states

Advanced Usage

Complex Nested Breadcrumbs

Breadcrumbs::define('admin.users.roles.edit', function ($trail, $user, $role) {
    $trail->parent('admin.users.show', $user);
    $trail->push('Edit Role: ' . $role->name, route('admin.users.roles.edit', [$user, $role]));
});

Conditional Breadcrumbs

Breadcrumbs::define('posts.show', function ($trail, $post) {
    if ($post->category) {
        $trail->parent('categories.show', $post->category);
    } else {
        $trail->parent('posts.index');
    }

    $trail->push($post->title, route('posts.show', $post));
});

Home/Dashboard Icon Support

The package includes special handling for the home breadcrumb, which is configurable:

// Define your home breadcrumb (defaults to 'dashboard')
Breadcrumbs::define('dashboard', function ($trail) {
    $trail->push('Dashboard', route('dashboard'));
});

By default, it renders with a house icon:

<!-- Automatically renders as -->
<flux:breadcrumbs.item href="/dashboard">
    <flux:icon icon="house" class="size-5 !text-orange-500 hover:!text-orange-600" />
</flux:breadcrumbs.item>

Customizing Home Display

You can customize how the home breadcrumb appears using the configuration options:

// config/breadcrumbs.php

// Change which route is considered "home"
'home_route' => 'home', // or 'dashboard', 'index', etc.

// Control the display style
'home_display' => 'icon',  // Options: 'icon', 'text', 'both'

// Change the icon used
'home_icon' => 'house',    // Options: 'house', 'home', 'squares-2x2', or any FluxUI icon

Display Options:

'icon' - Shows only the icon (default)
'text' - Shows only the text label
'both' - Shows both icon and text label

Testing

The package uses Pest for testing:

composer test

Or run Pest directly:

vendor/bin/pest

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

License

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

act-training / laravel-breadcrumbs

Maintainers

Details