README

A headless sidebar package for Laravel that allows you to create and manage sidebars with full customization support.

Originally forked from SpartnerNL/Laravel-Sidebar.

Installation

Require this package in your project:

composer require shopper/sidebar

Publish the config file:

php artisan vendor:publish --provider="Shopper\Sidebar\SidebarServiceProvider" --tag="sidebar-config"

Publish the views (optional, for customization):

php artisan vendor:publish --provider="Shopper\Sidebar\SidebarServiceProvider" --tag="sidebar-views"

Add the middleware to your route group or bootstrap/app.php:

// In a route group
Route::middleware(['web', \Shopper\Sidebar\Middleware\ResolveSidebars::class])
 ->group(function () {
 // Your routes
 });

// Or in bootstrap/app.php (Laravel 11+)
->withMiddleware(function (Middleware $middleware) {
 $middleware->appendToGroup('web', [
 \Shopper\Sidebar\Middleware\ResolveSidebars::class,
 ]);
})

Configuration

The config file (config/sidebar.php) allows you to customize:

return [
 // Caching method: null, 'static', or 'user-based'
 'cache' => [
 'method' => null,
 'duration' => 1440,
 ],

 // Sidebar dimensions (CSS values)
 'width' => '16.5rem',
 'collapsed_width' => '4.5rem',

 // Responsive breakpoint (pixels)
 'breakpoint' => 1024,

 // Allow sidebar to be collapsed on desktop
 'collapsible' => true,
];

Creating a Sidebar

1. Create a Sidebar Class

<?php

namespace App\Sidebar;

use Shopper\Sidebar\Contracts\Builder\Menu;
use Shopper\Sidebar\Contracts\Sidebar;

class AdminSidebar implements Sidebar
{
 public function __construct(private Menu $menu) {}

 public function build(): void
 {
 $this->menu->group('Main', function ($group) {
 $group->item('Dashboard')
 ->url('/dashboard')
 ->icon('heroicon-o-home')
 ->weight(1);

 $group->item('Users')
 ->url('/users')
 ->icon('heroicon-o-users')
 ->weight(2)
 ->items(function ($items) {
 $items->item('All Users')->url('/users');
 $items->item('Create User')->url('/users/create');
 });
 });

 $this->menu->group('Settings', function ($group) {
 $group->item('General')
 ->url('/settings')
 ->icon('heroicon-o-cog');
 });
 }

 public function getMenu(): Menu
 {
 return $this->menu;
 }
}

2. Register the Sidebar

Create an event listener or use the SidebarBuilder event:

<?php

namespace App\Providers;

use App\Sidebar\AdminSidebar;
use Illuminate\Support\ServiceProvider;
use Shopper\Sidebar\SidebarManager;

class SidebarServiceProvider extends ServiceProvider
{
 public function boot(SidebarManager $manager): void
 {
 $manager->register(AdminSidebar::class);
 }
}

Usage

The sidebar package provides two ways to render your sidebar:

Option 1: Livewire Component (Simple)

Use the built-in Livewire component for a ready-to-use sidebar with Alpine.js state management:

@livewire('sidebar', [
 'sidebarClass' => \App\Sidebar\AdminSidebar::class,
 'class' => 'your-sidebar-classes',
 'collapsible' => true,
])

The Livewire component includes:

• Alpine.js store integration ($store.sidebar)
• Collapse/expand functionality
• Responsive behavior (mobile/desktop)
• LocalStorage persistence

Option 2: Blade Components (Full Customization)

For complete control over the sidebar layout, use the SidebarRenderer directly in your Blade views:

{{-- layouts/sidebar.blade.php --}}
<aside
 class="sidebar"
 x-bind:class="{ 'sidebar-collapsed': $store.sidebar.isCollapsed }"
>
 {{-- Custom header with branding --}}
 <div class="sidebar-header">
 <img src="/logo.png" alt="Logo" />
 <span x-show="!$store.sidebar.isCollapsed">My App</span>
 </div>

 {{-- Sidebar menu (rendered by the package) --}}
 <nav class="sidebar-nav">
 {!! $sidebar !!}
 </nav>

 {{-- Custom footer --}}
 <div class="sidebar-footer">
 <a href="/settings">Settings</a>
 </div>
</aside>

Both options use the same underlying SidebarRenderer, which renders:

• item.blade.php - Individual menu items
• group.blade.php - Menu groups
• badge.blade.php - Item badges
• append.blade.php - Appended content

Alpine.js Store

The sidebar uses an Alpine.js store for state management. Initialize it in your JavaScript:

import Alpine from 'alpinejs'
import sidebarStore from '@shopper/sidebar/stores/sidebar'

Alpine.store('sidebar', sidebarStore())
Alpine.store('sidebar').init()

Store API

// State
$store.sidebar.isOpen // Mobile: sidebar visibility
$store.sidebar.isCollapsed // Desktop: collapsed state
$store.sidebar.collapsible // Whether collapse is enabled

// Methods
$store.sidebar.toggle() // Smart toggle (mobile: open/close, desktop: collapse/expand)
$store.sidebar.open() // Open sidebar (mobile)
$store.sidebar.close() // Close sidebar (mobile)
$store.sidebar.collapse() // Collapse sidebar (desktop)
$store.sidebar.expand() // Expand sidebar (desktop)
$store.sidebar.toggleCollapse()

// Group management
$store.sidebar.toggleGroup(label)
$store.sidebar.isGroupCollapsed(label)

CSS Variables

The sidebar dimensions are available as CSS variables:

:root {
 --sidebar-width: 16.5rem;
 --sidebar-collapsed-width: 4.5rem;
}

Inject them in your layout using the helper functions:

<style>
 :root {
 --sidebar-width: {{ \Shopper\Sidebar\sidebar_width() }};
 --sidebar-collapsed-width: {{ \Shopper\Sidebar\sidebar_collapsed_width() }};
 }
</style>

<body
 data-sidebar-breakpoint="{{ \Shopper\Sidebar\sidebar_breakpoint() }}"
 data-sidebar-collapsible="{{ \Shopper\Sidebar\sidebar_is_collapsible() ? 'true' : 'false' }}"
>

Helper Functions

The package provides namespaced helper functions:

\Shopper\Sidebar\sidebar_config($key, $default) // Get config value
\Shopper\Sidebar\sidebar_width() // Get sidebar width
\Shopper\Sidebar\sidebar_collapsed_width() // Get collapsed width
\Shopper\Sidebar\sidebar_breakpoint() // Get responsive breakpoint
\Shopper\Sidebar\sidebar_is_collapsible() // Check if collapsible

Menu Item Options

$group->item('Label')
 ->url('/path') // URL
 ->route('route.name') // Or use route name
 ->icon('heroicon-o-home') // Icon (Blade UI Kit format)
 ->weight(1) // Sort order
 ->badge('New') // Add badge
 ->newTab() // Open in new tab
 ->authorize(fn() => auth()->check()) // Authorization callback
 ->items(function ($items) { // Sub-items
 $items->item('Sub Item')->url('/sub');
 });

License

This package is licensed under MIT. You are free to use it in personal and commercial projects.