@publikit/bottomnavigation

Mobile horizontal bottom navigation bar component with scrollable items and optional pinned home item.

Features

• Mobile-First - Designed for mobile devices with md:hidden breakpoint
• Simple & Lightweight - Minimal dependencies, relies on @publikit/base
• Horizontal Scroll - Scrollable items with CSS snap scrolling
• Pinned Home Item - Optionally pin any item to the left via homeItemId
• Routing Adapter - Plug in any router (React Router, Next.js, etc.)
• Type-Safe - Full TypeScript support with exported types

Installation

npm install @publikit/bottomnavigation

Peer Dependencies

This package requires the following peer dependencies:

npm install react react-dom lucide-react tailwindcss @publikit/base

Tailwind CSS Setup

The component uses the following Tailwind utilities that may require configuration:

• bg-background - requires a background color in your theme
• scrollbar-none - requires tailwind-scrollbar plugin or custom utility
• safe-area-inset-bottom - for iOS safe area support

Quick Start

import { BottomNavigation } from '@publikit/bottomnavigation';
import { Home, Newspaper, MessageSquare } from 'lucide-react';

const items = [
  { id: 'home', name: 'Home', href: '/', icon: Home, badge: null },
  { id: 'feed', name: 'Feed', href: '/feed', icon: Newspaper, badge: 3 },
  { id: 'chat', name: 'Chat', href: '/chat', icon: MessageSquare, badge: null },
];

<BottomNavigation
  config={{
    items,
    homeItemId: 'home',
  }}
/>

With Routing Adapter

import { NavLink, useMatch } from 'react-router-dom';

<BottomNavigation
  config={{ items, homeItemId: 'home' }}
  adapters={{ routing: { Link: NavLink, useMatch } }}
/>

With Trailing Content

<BottomNavigation
  config={{ items, homeItemId: 'home' }}
  trailing={<WorkspaceSwitcher variant="mobile" />}
/>

With Badge Callback

<BottomNavigation
  config={{
    items,
    homeItemId: 'home',
    getItemBadge: (item) => unreadCounts[item.id] ?? null,
  }}
/>

Layout Structure

+---------------------------------------------+
| [Home] | [Item1] [Item2] [Item3] | [Trail]  |
|  fixed | ←  scrollable snap  →   |  fixed   |
+---------------------------------------------+

• Home: Pinned on the left (optional, set via homeItemId)
• Items: Scrollable middle section with snap
• Trailing: Fixed on the right (optional)

API Reference

BottomNavigationProps

| Prop | Type | Required | Description | |------|------|----------|-------------| | config | BottomNavigationConfig | Yes | Navigation configuration | | adapters | BottomNavigationAdapters | No | Optional routing adapter | | trailing | ReactNode | No | Trailing content (e.g., workspace switcher) | | className | string | No | Additional class for the root <nav> element |

BottomNavigationConfig

| Field | Type | Required | Description | |-------|------|----------|-------------| | items | NavigationItem[] | Yes | Navigation items to display | | homeItemId | string | No | ID of the item to pin as "home" on the left | | getItemBadge | (item) => number \| null | No | Badge value resolver callback |

NavigationItem

| Field | Type | Required | Description | |-------|------|----------|-------------| | id | string | Yes | Unique identifier | | name | string | Yes | Display label (pre-translated by consumer) | | href | string | Yes | Navigation path | | icon | LucideIcon | Yes | Icon component from lucide-react | | badge | number \| null | Yes | Default badge value (null to hide) | | visible | boolean | No | Whether item is visible |

License

MIT