Weave Code
Laravel Navigation Laravel Package
spatie/laravel-navigation
Define a navigation tree for Laravel apps and reuse it to build menus, breadcrumbs, and other nav UI. Manage sections, nested items, and active state in PHP, register navigation via service providers/container events, and render however you like.
Manage menus, breadcrumbs, and other navigational elements in Laravel apps
Frequently asked questions about Laravel Navigation
- How does spatie/laravel-navigation differ from hardcoding menus in Blade templates?
- This package abstracts navigation logic into reusable PHP structures, separating data from presentation. Unlike hardcoded Blade menus, it supports dynamic conditions (e.g., user roles), nested hierarchies, and works seamlessly with frontend frameworks like Vue or React via Inertia.js. You define the navigation tree once and render it anywhere—Blade, JavaScript, or APIs.
- Can I use this package with Laravel Livewire or Alpine.js for dynamic navigation?
- Yes. The package provides structured navigation data (arrays/collections) that you can pass to Livewire props or Alpine.js reactivity. For example, fetch the navigation tree via a Livewire component or expose it as a global Alpine store. The renderless design ensures flexibility for client-side updates without server-side HTML generation.
- What Laravel versions does spatie/laravel-navigation support?
- The package is officially tested with Laravel 9.x and 10.x. It leverages modern Laravel features like route() helpers and service container events, so it integrates smoothly with these versions. For older Laravel 8.x apps, check the package’s GitHub for compatibility notes or consider Laravel Menu as an alternative.
- How do I handle multi-language navigation (e.g., i18n) with this package?
- You can dynamically build navigation trees based on the current locale using Laravel’s app()->getLocale() or middleware. For example, conditionally add sections with translated labels or route names. The package doesn’t enforce i18n, but its fluent API makes it easy to integrate with packages like spatie/laravel-translatable or Laravel’s built-in localization.
- Is there a way to cache navigation trees for performance in large apps?
- The package doesn’t include built-in caching, but you can cache the navigation tree manually using Laravel’s cache helpers (e.g., Cache::remember). For dynamic navigation (e.g., user-specific menus), cache with a unique key like `navigation_{user_id}_{locale}`. This is especially useful for admin panels or multi-tenant apps where navigation changes infrequently.
- How do I test navigation logic, especially active state detection?
- Test navigation by asserting the structure of the returned array/collection. For active state logic, mock the current route or request (e.g., using Laravel’s testing helpers like routing()->get()) and verify the `isActive()` method or similar checks. Example: `assertTrue($navigation->get('Blog')->isActive());`. Use PHPUnit or Pest for unit tests.
- Can I migrate from hardcoded Blade menus to this package incrementally?
- Yes. Start by replacing one menu (e.g., primary navigation) with the package’s API. Use the `Navigation::make()` method to rebuild your existing menu structure, then gradually migrate other menus. The package’s service provider integration lets you centralize navigation logic, making phased adoption easier. Blade templates can consume the new data via `@foreach` loops.
- What if I need to support both Blade and a frontend framework (e.g., Vue) in the same app?
- The renderless design is perfect for this. Define your navigation tree once in a service provider or controller, then expose it to both Blade (via `@foreach`) and your frontend (via API routes or Inertia.js props). For Vue/React, pass the navigation data as a prop or global state. This avoids duplication and keeps your navigation logic DRY.
- How do I handle nested routes or complex active state logic (e.g., query params)?
- Use the package’s `add()` and `addIf()` methods to build nested structures. For active state, leverage Laravel’s `request()` helpers or custom logic in closures. Example: Check for query params like `request()->query('tab')` to highlight active sections. The package doesn’t enforce active state rules, so you can tailor it to your routing conventions.
- Are there alternatives to spatie/laravel-navigation for Laravel navigation?
- Yes. For HTML-focused menus, consider `spatie/laravel-menu` (the predecessor) or `orchid/software` for admin panels. For API-driven navigation, Laravel’s built-in route lists or custom Eloquent models may suffice. However, this package stands out for its renderless, modular approach, which is ideal for modern Laravel apps with frontend frameworks or headless architectures.
Weaver
How can I help you explore Laravel packages today?