Filament Slim Scrollbar Laravel Package

Getting Started

First Steps

1. Installation Run a single Composer command to add the package:

   composer require aymanalhattami/filament-slim-scrollbar
   

   No additional configuration is required for basic usage—Filament 3/4/5 auto-detects the package.

2. First Use Case

   • Immediate Impact: Open your Filament admin panel. The scrollbars in sidebars, tables, and modals will now appear slim by default.
   • Verification: Test dark/light mode toggles to confirm consistent styling across themes.

3. Where to Look First

   • Package Source: src/FilamentSlimScrollbarServiceProvider.php (for registration logic).
   • CSS Overrides: resources/views/vendor/filament-slim-scrollbar/styles.blade.php (if you need to customize styles).

Implementation Patterns

Core Workflows

1. Default Integration

   • Zero Configuration: The package auto-loads CSS via Filament’s asset pipeline. No manual file inclusion is needed.
   • Scope: Applies to all scrollable elements in Filament (sidebars, tables, modals, etc.).

2. Targeted Application

   • Selective Activation: To apply slim scrollbars to a specific component (e.g., a custom table), add this class to the container:

     <div class="filament-slim-scrollbar">
         <!-- Your scrollable content -->
     </div>
     

   • Exclusion: Override styles for specific elements using !important or higher specificity in your app’s CSS.

3. Dark/Light Mode Handling

   • The package dynamically switches scrollbar styles based on Filament’s theme system. No manual toggling is required.

4. Testing

   • Browser Compatibility: Test in Chrome, Firefox (v70+), and Edge. Firefox support is enabled only on large screens by default (configurable).
   • Edge Cases: Verify scrollbar behavior in nested containers (e.g., modals within scrollable tables).

Integration Tips

• Filament Panels: Works out-of-the-box with Filament’s default panels. For custom panels, ensure the filament-slim-scrollbar CSS is loaded (it is by default).
• Custom Components: If building a Filament resource/page with custom scrollable sections, wrap them in a <div> with the filament-slim-scrollbar class.
• Asset Pipeline: If using Laravel Mix/Vite, the package’s CSS is injected via Filament’s styles hook. No additional bundling is needed.

Gotchas and Tips

Common Pitfalls

1. Firefox Limitations

   • Issue: Firefox (pre-v70) may ignore slim scrollbar styles due to browser quirks. The package applies Firefox-specific styles only on large screens (min-width: 1024px) by default.
   • Fix: Adjust the breakpoint in the package’s CSS or disable Firefox support entirely by overriding:

     @media (min-width: 1024px) {
         html:not(.firefox) ::-webkit-scrollbar { /* Your custom styles */ }
     }
     

2. Nested Scrollbars

   • Issue: Double scrollbars may appear in nested scrollable containers (e.g., a modal inside a scrollable sidebar).
   • Fix: Add overflow: hidden to the parent container or use position: fixed for modals.

3. Custom CSS Conflicts

   • Issue: Existing ::-webkit-scrollbar styles in your app may conflict with the package.
   • Fix: Use higher specificity or reset scrollbar styles in your CSS:

     ::-webkit-scrollbar {
         width: 0 !important;
         height: 0 !important;
     }
     

4. Filament Version Mismatch

   • Issue: Using the package with Filament 2.x will break (requires version 1.x of the package).
   • Fix: Check the README for version compatibility and update accordingly.

Debugging Tips

• Inspect Elements: Use browser dev tools to verify the package’s CSS is loaded (look for filament-slim-scrollbar classes).
• Disable Cache: Clear Filament’s view cache (php artisan view:clear) if styles aren’t applying.
• Check for Overrides: Search your project for ::-webkit-scrollbar to identify conflicting styles.

Extension Points

1. Custom Styling

   • Publish the package’s assets to override default styles:

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

   • Edit the published CSS file at resources/views/vendor/filament-slim-scrollbar/styles.blade.php.

2. Conditional Loading

   • Disable slim scrollbars for specific pages by adding this to your Blade layout:

     <style>
         .no-slim-scrollbar ::-webkit-scrollbar {
             width: auto;
             height: auto;
         }
     </style>
     

     Then add the no-slim-scrollbar class to containers where slim scrollbars are unwanted.

3. Dynamic Theming

   • Extend the package to support custom themes by hooking into Filament’s Theme service:

     use Filament\Support\Facades\FilamentTheme;
     
     FilamentTheme::register(function () {
         return [
             'scrollbar-width' => 'thin', // or 'auto'
         ];
     });
     

     Then update the package’s CSS to read this value.

Performance Notes

• Zero Overhead: The package adds no JavaScript and minimal CSS (~1KB). Ideal for performance-sensitive apps.
• Critical CSS: Styles are loaded asynchronously via Filament’s asset pipeline, avoiding render-blocking.