Filament Collapsible Sidebar Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require slym758/filament-collapsible-sidebar
   

2. Register the plugin in your PanelProvider:

   use Slym758\CollapsibleSidebar\CollapsibleSidebarPlugin;
   
   public function panel(Panel $panel): Panel {
       return $panel->plugins([
           CollapsibleSidebarPlugin::make(),
       ]);
   }
   

3. Clear cached views (if needed):

   php artisan view:clear
   

First Use Case

• Immediate UI improvement: The plugin adds a collapsible sidebar toggle button (visible only on desktop) with smooth animations. Test by resizing your browser window or toggling the button manually.

Implementation Patterns

Core Workflow

1. State Persistence:

   • The plugin automatically saves the collapsed/expanded state in localStorage under the key filament-collapsible-sidebar-state.
   • Customization: Override the storage key via plugin configuration (see below).

2. Responsive Handling:

   • The sidebar is hidden on mobile by default (media query: max-width: 767px).
   • Custom breakpoint: Extend the plugin’s CSS or use Filament’s responsive helpers to adjust.

3. Icon-Only View:

   • When collapsed, navigation items display only icons (no text).
   • Custom icons: Ensure your NavigationItem uses Icon components (e.g., <x-filament-icons::heroicon-o-home />).

Integration Tips

• Custom Toggle Button: Modify the toggle button’s appearance by overriding the plugin’s Blade view (resources/views/vendor/filament-collapsible-sidebar/toggle.blade.php). Example:

  <button class="custom-toggle">
      {{ $toggleIcon }}
  </button>
  

• Conditional Loading: Disable the plugin for specific panels or users by checking conditions in panel():

  ->plugins([
      auth()->user()->can('toggle-sidebar') ? CollapsibleSidebarPlugin::make() : null,
  ])
  

• Animation Tweaks: Adjust CSS transitions in the plugin’s assets (e.g., public/vendor/filament-collapsible-sidebar/css/collapsible-sidebar.css):

  .sidebar-transition {
      transition: all 0.3s ease-in-out; /* Customize duration/easing */
  }
  

• Dark Mode: The plugin supports dark mode out-of-the-box. For custom themes, ensure your Filament theme includes dark-mode CSS variables.

Gotchas and Tips

Pitfalls

1. LocalStorage Conflicts:

   • If multiple Filament panels use this plugin, they may overwrite each other’s localStorage state.
   • Fix: Use a unique storage key per panel:

     CollapsibleSidebarPlugin::make()->storageKey('panel-name-sidebar-state');
     

2. Mobile Detection:

   • The plugin hides the sidebar on mobile via CSS (@media (max-width: 767px)).
   • Issue: If your app uses a custom mobile breakpoint, the toggle button may still appear.
   • Fix: Override the media query in your CSS or extend the plugin’s JavaScript.

3. Icon Visibility:

   • If navigation items lack icons, the collapsed view will show broken links or empty space.
   • Fix: Ensure all NavigationItems include an Icon component.

4. Caching:

   • After installing, clear Filament’s view cache:

     php artisan filament:cache-reset
     

Debugging

• State Not Persisting: Check the browser’s DevTools (Application > LocalStorage) for the filament-collapsible-sidebar-state key. If missing, verify:

  • The plugin is registered in panel().
  • No JavaScript errors (check Console tab).

• Toggle Button Missing: Ensure the plugin is loaded in the correct panel. Test in an incognito window to rule out cached views.

Extension Points

1. Custom Toggle Logic: Extend the plugin’s JavaScript to add custom toggle behavior:

   document.addEventListener('filament-collapsible-sidebar-initialized', (e) => {
       const toggleButton = e.detail.toggleButton;
       toggleButton.addEventListener('click', (e) => {
           // Custom logic (e.g., disable toggle for admins)
           if (userIsAdmin()) return;
       });
   });
   

2. Server-Side State: For critical apps, sync the sidebar state with your database:

   // In your PanelProvider
   ->plugins([
       CollapsibleSidebarPlugin::make()->useServerSideState(fn () => User::find(auth()->id())->sidebar_collapsed),
   ]);
   

3. Animation Events: Listen for animation start/end via JavaScript:

   document.addEventListener('filament-collapsible-sidebar-animation-start', (e) => {
       console.log('Sidebar animating:', e.detail.direction);
   });
   

Configuration Quirks

• Default Collapsed State: Set the initial state via configuration:

  CollapsibleSidebarPlugin::make()->defaultCollapsed(true);
  

• Exclude Pages: Disable the plugin for specific pages by checking the current URL in the toggle button’s logic (requires JS extension).

• Accessibility: The toggle button includes ARIA attributes (aria-expanded). For full compliance, ensure your theme’s icons are accessible (e.g., include aria-label).