Mobile Bottom Nav Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require hammadzafar05/mobile-bottom-nav
   

   No additional configuration or publishing is required.

2. Register the Plugin: Add the plugin to your Filament panel provider (e.g., PanelServiceProvider):

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \Hammadzafar05\MobileBottomNav\MobileBottomNav::make(),
               // ... other plugins
           ]);
   }
   

3. First Use Case:

   • Navigate to your Filament admin panel on a mobile device (or simulate via browser dev tools: Ctrl+Shift+M).
   • The bottom navigation bar will automatically appear, populated with items from your Filament navigation registry (e.g., pages, resources, widgets).
   • Test tapping items to verify they route correctly.

Implementation Patterns

Core Workflows

1. Automatic Navigation Integration:

   • The package scans your Filament navigation registry (e.g., Navigation::items()) and mirrors those items in the bottom bar.
   • Example: If you have a Dashboard page and a Posts resource, both will appear as tappable icons in the bottom nav.
   • Customization: Override the default items by publishing the config:

     php artisan vendor:publish --provider="Hammadzafar05\MobileBottomNav\MobileBottomNavServiceProvider" --tag="mobile-bottom-nav-config"
     

     Then modify config/mobile-bottom-nav.php to specify nav_items.

2. Responsive Behavior:

   • The bottom nav only appears on mobile viewports (default breakpoint: 768px).
   • Use the breakpoint config option to adjust:

     MobileBottomNav::make()->configureUsing(function (MobileBottomNav $plugin) {
         $plugin->breakpoint = 992; // Show on larger screens
     });
     

3. Sidebar Integration:

   • If your panel uses a sidebar (e.g., Filament’s default), the bottom nav collapses into a hamburger menu on mobile.
   • Enable/disable via config:

     'sidebar_integration' => true,
     

4. Dynamic Badges:

   • Add badges to items (e.g., unread notifications) by extending the navigation item:

     Navigation::items([
         NavigationItem::make('Dashboard')
             ->icon('heroicon-o-home')
             ->badge(5) // Shows a "5" badge
             ->url(fn () => route('filament.admin.pages.dashboard')),
     ]);
     

5. Dark Mode Support:

   • The package automatically adapts to Filament’s dark mode settings.
   • Customize colors via the colors config:

     'colors' => [
         'light' => ['background' => '#f8fafc', 'icon' => '#475569'],
         'dark' => ['background' => '#2d3748', 'icon' => '#e2e8f0'],
     ],
     

Advanced Patterns

1. Conditional Item Visibility:

   • Hide items on mobile by adding a mobile_hidden flag to navigation items:

     NavigationItem::make('Settings')
         ->mobileHidden(true)
         ->url(...),
     

2. Custom Icons:

   • Use Heroicons or custom SVG icons:

     NavigationItem::make('Reports')
         ->icon('heroicon-o-chart-bar')
         ->url(...),
     

3. Programmatic Control:

   • Toggle the bottom nav via JavaScript (e.g., for modal overlays):

     window.MobileBottomNav.hide(); // Extend the package’s JS API if needed
     

   • Note: The package exposes a window.MobileBottomNav object for basic control.

4. Localization:

   • Translate item labels using Filament’s localization system:

     NavigationItem::make(__('filament-bottom-nav.dashboard'))
         ->url(...),
     

Gotchas and Tips

Common Pitfalls

1. Navigation Registry Mismatch:

   • Issue: Bottom nav items don’t match your expectations.
   • Cause: The package relies on Navigation::items(). Ensure your navigation items are registered before the panel loads.
   • Fix: Verify your PanelServiceProvider or NavigationServiceProvider is correctly configured.

2. Safe Area Insets Not Working:

   • Issue: Bottom nav is hidden behind mobile notches (e.g., iPhone X).
   • Cause: CSS env(safe-area-inset-bottom) may be overridden.
   • Fix: Override the package’s CSS via your panel’s assets:

     .filament-mobile-bottom-nav {
         padding-bottom: env(safe-area-inset-bottom);
     }
     

3. Duplicate Items:

   • Issue: Items appear in both the sidebar and bottom nav.
   • Cause: The package duplicates items from the navigation registry.
   • Fix: Use mobileHidden(true) on sidebar-only items or vice versa.

4. Performance on Large Navs:

   • Issue: Lag when navigating with many items.
   • Cause: Heavy DOM manipulation with large navigation arrays.
   • Fix: Limit items via config:

     'max_items' => 5, // Show only top 5 items
     

Debugging Tips

1. Inspect the Rendered HTML:

   • Open browser dev tools (F12) and check if the bottom nav renders:

     <div class="filament-mobile-bottom-nav">...</div>
     

   • If missing, verify the plugin is registered in panel() and no JavaScript errors block it.

2. Check JavaScript Console:

   • Look for errors like:

     MobileBottomNav is not defined
     

   • Fix: Ensure the package’s JS is loaded (check resources/js/filament/app.js or your panel’s JS bundle).

3. Disable Caching:

   • If changes don’t reflect, clear Filament’s cache:

     php artisan filament:cache:clear
     

Extension Points

1. Custom Templates:

   • Override the Blade template by publishing the view:

     php artisan vendor:publish --provider="Hammadzafar05\MobileBottomNav\MobileBottomNavServiceProvider" --tag="mobile-bottom-nav-views"
     

   • Modify resources/views/vendor/mobile-bottom-nav.blade.php.

2. Add Custom Items:

   • Extend the navigation registry dynamically:

     Navigation::macro('addMobileBottomNavItem', function ($item) {
         $this->items[] = $item->mobileHidden(false);
     });
     

3. Event Listeners:

   • Listen for bottom nav events (e.g., item click) by extending the package:

     MobileBottomNav::make()->onItemClick(function (string $url) {
         // Log or analytics
     });
     

4. Dark Mode Overrides:

   • Force dark/light mode via config:

     'force_dark_mode' => env('MOBILE_NAV_DARK_MODE', false),
     

Pro Tips

• Test on Real Devices: Emulators may not trigger mobile viewports correctly. Test on actual iOS/Android devices.
• Combine with Filament’s Mobile Layout: Use the package alongside Filament’s built-in mobile layout for a cohesive experience.
• Accessibility: Ensure icons have ARIA labels for screen readers by extending the template:

  <button aria-label="{{ $item['label'] }}">
      {{ $item['icon'] }}
  </button>
  

• Performance: For panels with >10 nav items, consider lazy-loading the bottom nav or using a collapsible design.