Filament Slim Scrollbar Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require aymanalhattami/filament-slim-scrollbar:^2.1.1
   

   Publish the package assets (if needed):

   php artisan vendor:publish --provider="AymanAlhattami\FilamentSlimScrollbar\FilamentSlimScrollbarServiceProvider" --tag="filament-slim-scrollbar-assets"
   

2. Enable the Package Add the service provider to config/app.php (if not auto-discovered):

   AymanAlhattami\FilamentSlimScrollbar\FilamentSlimScrollbarServiceProvider::class,
   

3. First Use Case The package now supports Filament v4 and v5 out-of-the-box. No additional configuration is required for default scrollbars (sidebar, tables, modals). Verify by refreshing a Filament page—scrollbars should appear slim in both versions.

Where to Look First

• Documentation: GitHub README (updated with versioning details).
• Source Code: Focus on resources/views/extensions/filament-slim-scrollbar.blade.php for customization hooks.
• Config: Check config/filament-slim-scrollbar.php (if published) for global overrides, including version-specific configurations.

Implementation Patterns

Core Workflows

1. Default Integration for Filament v4/v5

   • Automatically targets Filament’s built-in scrollable elements (sidebar, tables, modals) in both v4 and v5.
   • No manual CSS/JS required. Example:

     // FilamentPanel.php (if extending)
     protected function getFilamentApp(): Filament\Filament {
         return parent::getFilamentApp()
             ->withGlobalSearch()
             ->withSlimScrollbars(); // Package handles this via service provider
     }
     

2. Targeting Specific Elements Use the data-slim-scrollbar attribute on custom HTML elements:

   <div data-slim-scrollbar class="h-64 overflow-y-auto">
       <!-- Content -->
   </div>
   

   Laravel Blade Example:

   <x-filament::section data-slim-scrollbar>
       {{ $content }}
   </x-filament::section>
   

3. Dark/Light Mode Support The package auto-detects Filament’s theme mode. Override via config:

   // config/filament-slim-scrollbar.php
   'force_light_mode' => env('FORCE_LIGHT_SCROLLBAR', false),
   

4. Customizing Scrollbar Styles Extend the base styles by publishing assets and overriding:

   /* resources/css/filament-slim-scrollbar.css */
   .slimScrollbar-track {
       background: #333; /* Custom track color */
   }
   

Integration Tips

• Filament v4/v5 Plugins: Ensure your scrollable components use data-slim-scrollbar for consistency in both versions.
• Tailwind CSS: The package remains compatible with Tailwind. Use utility classes like overflow-auto alongside data-slim-scrollbar.
• Performance: Zero JavaScript overhead; ideal for large datasets in tables across Filament versions.
• Testing: Test in both dark/light modes and Filament v4/v5 early—scrollbar colors may need adjustment.

Gotchas and Tips

Pitfalls

1. Version-Specific Conflicts

   • Filament v5 may introduce new class names or structure. Inspect elements in both versions to ensure data-slim-scrollbar is applied correctly.
   • Fix: Use browser dev tools to verify selectors like .filament-v5 .slimScrollbar-* if needed.

2. Nested Scrollables

   • Nested scrollable containers (e.g., tables inside modals) may require explicit targeting in both Filament versions:

     <div data-slim-scrollbar class="overflow-hidden">
         <table data-slim-scrollbar class="overflow-auto">
             <!-- Rows -->
         </table>
     </div>
     

3. Third-Party Packages

   • Some Filament add-ons (e.g., filament-spatie-laravel-medialibrary) may override scrollbar styles in v4/v5. Inspect their CSS and add:

     .filament-v4 .filament-spatie-medialibrary .slimScrollbar-track,
     .filament-v5 .filament-spatie-medialibrary .slimScrollbar-track {
         /* Override here */
     }
     

4. Browser Quirks

   • Firefox/Edge may render scrollbars slightly differently across Filament versions. Test early in both v4 and v5.
   • Debug: Use browser dev tools to inspect .slimScrollbar-* classes in both versions.

Debugging Tips

• Disable Cache: Clear Filament’s view cache if styles don’t apply:

  php artisan filament:cache-clear
  

• Inspect Elements: Verify data-slim-scrollbar is present on target elements in both Filament v4 and v5.
• Console Logs: Check for CSS conflicts by inspecting the published CSS file after:

  php artisan vendor:publish --tag=filament-slim-scrollbar-assets --force
  

Extension Points

1. Custom Scrollbar Colors Override via config or published CSS for both Filament versions:

   // config/filament-slim-scrollbar.php
   'colors' => [
       'track' => '#e2e8f0', // Light mode (v4/v5)
       'thumb' => '#4a5568',
       'dark_track' => '#4a5568', // Dark mode (v4/v5)
       'dark_thumb' => '#e2e8f0',
   ],
   

2. Conditional Loading by Filament Version Disable or customize for specific Filament versions via middleware or a trait:

   // app/Providers/FilamentServiceProvider.php
   Filament::serving(function () {
       if (app()->version() === '5.0.*' && request()->routeIs('filament.pages.no-scrollbar')) {
           app()->singleton(FilamentSlimScrollbar::class, fn() => null);
       }
   });
   

3. JavaScript Hooks (Advanced) Though CSS-only, extend with JS if needed for version-specific tweaks:

   document.addEventListener('DOMContentLoaded', () => {
       const slimElements = document.querySelectorAll('[data-slim-scrollbar]');
       slimElements.forEach(el => {
           if (document.body.classList.contains('filament-v5')) {
               el.style.setProperty('--slim-scrollbar-width', '8px');
           }
       });
   });
   

Pro Tips

• Consistency: Use the package’s scrollbar for all Filament pages (v4/v5) to maintain UI cohesion.
• Accessibility: Slim scrollbars improve touch targets; test with keyboard navigation in both versions.
• Performance: Ideal for tables with 1000+ rows—reduces visual clutter without JS in Filament v4/v5.
• Version-Specific Testing: Always test new features or customizations in both Filament v4 and v5 environments.