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).
   • Key Improvement (v1.3): The bottom nav now preserves the exact order of your Filament sidebar navigation, including group-based sorting. 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.
   • Auto-Discovery Mode (v1.3 Fix): If you’re not explicitly calling Navigation::items(), the package now respects Filament’s native sidebar order (including group-based sorting) instead of re-sorting globally. This ensures consistency with your app’s primary navigation.
   • 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 Order Mismatch (v1.3 Fix):

   • Issue: Bottom nav items appear in a different order than the sidebar.
   • Cause (Pre-v1.3): The package’s auto-discovery mode (extractFromNavigation()) re-sorted all navigation items globally, ignoring group-based sorting.
   • Fix (v1.3): The package now preserves Filament’s native sidebar order. If issues persist, explicitly define nav_items in the config to override auto-discovery:

     'nav_items' => [
         // Manually specify items in your desired order
     ],
     

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 Navigation Order:

   • Compare the bottom nav order with your sidebar. If they differ, explicitly define nav_items in the config or ensure your Navigation::items() call includes all relevant groups.

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.
• Auto-Discovery vs. Manual Items: Prefer nav_items config for complex navigation structures to avoid unintended sorting behavior.