@mks/mobile-bottom-nav

Production-ready mobile bottom navigation component for Next.js with advanced viewport handling, SSR support, and complete TypeScript integration.

Features

• 🚀 Next.js Optimized: Full SSR/CSR support with Next.js Link and Image
• 📱 Advanced Viewport Handling: Supports 100dvh, 100svh, 100lvh with fallbacks
• 🎨 Tailwind CSS: 95% utility classes, minimal custom CSS
• 🔧 TypeScript: Complete type safety and IntelliSense
• ♿ Accessible: WCAG compliant with ARIA attributes
• 🎯 Platform Detection: iOS/Android specific optimizations
• 🛡️ Safe Area Support: Respects device notches and home indicators
• 🖼️ Flexible Icons: Support for React components or Next/Image
• 🎭 Multiple Variants: Default, floating, and minimal styles
• 📦 Lightweight: ~8KB minified + gzipped

Installation

npm install @mks/mobile-bottom-nav
# or
yarn add @mks/mobile-bottom-nav
# or
bun add @mks/mobile-bottom-nav

Quick Start

import { MobileBottomNav } from '@mks/mobile-bottom-nav'
import '@mks/mobile-bottom-nav/styles' // Critical CSS (~1KB)
import { Home, Search, Plus, Heart, User } from 'lucide-react'

const navItems = [
  { 
    name: 'Home', 
    href: '/', 
    icon: Home,
    alt: 'Go to homepage'
  },
  { 
    name: 'Search', 
    href: '/search', 
    icon: Search 
  },
  { 
    name: 'Create', 
    href: '/create', 
    icon: Plus,
    badge: '3' // Optional badge
  },
  { 
    name: 'Favorites', 
    href: '/likes', 
    icon: Heart 
  },
  { 
    name: 'Profile', 
    href: '/profile', 
    icon: User 
  }
]

export default function Layout({ children }) {
  return (
    <>
      {children}
      <MobileBottomNav 
        items={navItems}
        variant="default"
        showLabels={true}
        iconSize="md"
      />
    </>
  )
}

Advanced Usage

With Next/Image

const navItems = [
  {
    name: 'Dashboard',
    href: '/dashboard',
    image: {
      src: '/icons/dashboard.svg',
      alt: 'Dashboard icon',
      width: 24,
      height: 24
    }
  },
  // Mix icons and images
  {
    name: 'Settings',
    href: '/settings',
    icon: Settings // Lucide icon
  }
]

Floating Variant

<MobileBottomNav 
  items={navItems}
  variant="floating" // Adds margin and rounded corners
  className="shadow-2xl" // Additional styling
/>

Controlled Active State

function MyApp() {
  const [activeIndex, setActiveIndex] = useState(0)
  
  return (
    <MobileBottomNav 
      items={navItems}
      activeIndex={activeIndex}
      onNavigate={(item, index) => {
        console.log('Navigating to:', item.href)
        setActiveIndex(index)
      }}
    />
  )
}

Custom Active Indicator

<MobileBottomNav 
  items={navItems}
  showActiveIndicator={true}
  activeIndicator={
    <div className="absolute -bottom-1 w-8 h-1 bg-gradient-to-r from-blue-500 to-purple-500 rounded-full" />
  }
/>

External Links

const navItems = [
  {
    name: 'Documentation',
    href: 'https://docs.example.com',
    icon: Book,
    useNextLink: false // Forces regular anchor tag
  }
]

Props

MobileBottomNavProps

| Prop | Type | Default | Description | |------|------|---------|-------------| | items | NavItemConfig[] | Required | Navigation items configuration | | className | string | - | Additional container classes | | activeIndex | number | - | Controlled active item index | | onNavigate | (item, index) => void | - | Navigation callback | | debug | boolean | false | Show debug information | | variant | 'default' \| 'floating' \| 'minimal' | 'default' | Visual style variant | | showLabels | boolean | true | Show text labels | | iconSize | 'sm' \| 'md' \| 'lg' | 'md' | Icon size | | showActiveIndicator | boolean | false | Show active indicator | | activeIndicator | ReactNode | - | Custom active indicator | | sticky | boolean | true | Use sticky positioning | | zIndex | number | 40 | Z-index value |

NavItemConfig

| Prop | Type | Description | |------|------|-------------| | name | string | Display text | | href | string | Navigation URL | | alt | string | Accessibility text | | icon | ComponentType | React icon component | | image | object | Next/Image config | | badge | ReactNode | Badge content | | onClick | () => void | Click handler | | className | string | Item classes | | useNextLink | boolean | Force Link usage |

Styling

The component uses Tailwind CSS classes. Ensure your project has Tailwind configured.

Required Tailwind Classes

The component expects these Tailwind utilities:

• Layout: flex, sticky, fixed, bottom-0
• Spacing: px-2, py-1, mb-1
• Colors: bg-background, text-primary, text-muted-foreground
• Effects: backdrop-blur-md, border, rounded-lg
• Animations: transition-all, duration-200, active:scale-95

Custom CSS Variables

Add to your global CSS for theming:

:root {
  --navbar-bottom: 0px; /* Set dynamically by component */
}

Browser Support

• Chrome/Edge 108+ (100dvh support)
• Safari iOS 15.4+
• Firefox 101+
• Samsung Internet 19+

Includes automatic fallbacks for older browsers.

TypeScript

Full TypeScript support with exported types:

import type { 
  NavItemConfig, 
  MobileBottomNavProps,
  NavVariant,
  IconSize 
} from '@mks/mobile-bottom-nav'

Performance

• Lazy loads images with Next/Image
• Uses React.memo for items
• Throttled viewport listeners (60fps)
• CSS containment for reflow optimization
• Touch-optimized with touch-action: manipulation

Accessibility

• Semantic HTML with <nav> element
• ARIA labels and current page indication
• Keyboard navigation support
• Focus indicators
• Screen reader friendly

License

MIT

Author

MKS2508