@pmcs/floating-navigation

A beautiful, accessible floating navigation component for React applications

✨ Features

• 🎨 Beautiful Design - Matches professional UI standards
• ♿ Fully Accessible - ARIA compliant with keyboard navigation
• 📱 Responsive - Works on desktop, tablet, and mobile
• 🎯 TypeScript - Full TypeScript support with comprehensive types
• 🎨 Themeable - Customizable design system
• 📦 Lightweight - Only ~3KB gzipped
• 🔧 Zero Config - Works out of the box with sensible defaults
• 🚀 Framework Agnostic - Works with Next.js, CRA, Vite, etc.

🚀 Quick Start

Installation

npm install @pmcs/floating-navigation
# or
yarn add @pmcs/floating-navigation
# or
pnpm add @pmcs/floating-navigation

Basic Usage

import { FloatingNavigation } from '@pmcs/floating-navigation';
import { Home, Folder, Settings, Users } from 'lucide-react';

function App() {
  return (
    <div>
      <FloatingNavigation />
      <main>Your app content...</main>
    </div>
  );
}

Custom Navigation Items

import { FloatingNavigation, type NavigationItem } from '@pmcs/floating-navigation';
import { Dashboard, Analytics, Settings, Profile } from 'lucide-react';

const customItems: NavigationItem[] = [
  { id: 'dashboard', icon: Dashboard, label: 'Dashboard', href: '/dashboard' },
  { id: 'analytics', icon: Analytics, label: 'Analytics', href: '/analytics' },
  { id: 'settings', icon: Settings, label: 'Settings', href: '/settings' },
  { id: 'profile', icon: Profile, label: 'Profile', href: '/profile' },
];

function App() {
  return (
    <FloatingNavigation
      items={customItems}
      position="right"
      initialActiveItem="dashboard"
      onItemClick={(item) => {
        console.log('Navigating to:', item.label);
        // Handle navigation (React Router, Next.js Router, etc.)
      }}
    />
  );
}

📚 API Reference

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | items | NavigationItem[] | Default items | Array of navigation items | | initialActiveItem | string | 'home' | ID of initially active item | | position | 'left' \| 'right' | 'left' | Position of the navigation | | onItemClick | (item: NavigationItem) => void | undefined | Click handler for items | | style | React.CSSProperties | undefined | Custom styles | | className | string | undefined | CSS class name |

NavigationItem

interface NavigationItem {
  id: string;           // Unique identifier
  icon: LucideIcon;     // Lucide React icon component
  label: string;        // Accessible label
  href?: string;        // Optional URL/route
  disabled?: boolean;   // Optional disabled state
}

🎨 Theming

Custom Theme

import { FloatingNavigation, createStyles } from '@pmcs/floating-navigation';

const darkTheme = {
  colors: {
    background: 'hsl(220 13% 18%)',
    border: 'hsl(217 19% 27%)',
    active: 'hsl(224 71% 4%)',
    hover: 'hsl(215 28% 17%)',
    text: 'hsl(213 31% 91%)',
  },
  // ... other theme properties
};

function App() {
  return (
    <FloatingNavigation
      style={createStyles(darkTheme).container}
    />
  );
}

🔌 Framework Integration

Next.js

import { FloatingNavigation } from '@pmcs/floating-navigation';
import { useRouter } from 'next/router';

function Navigation() {
  const router = useRouter();

  return (
    <FloatingNavigation
      onItemClick={(item) => {
        if (item.href) {
          router.push(item.href);
        }
      }}
    />
  );
}

React Router

import { FloatingNavigation } from '@pmcs/floating-navigation';
import { useNavigate } from 'react-router-dom';

function Navigation() {
  const navigate = useNavigate();

  return (
    <FloatingNavigation
      onItemClick={(item) => {
        if (item.href) {
          navigate(item.href);
        }
      }}
    />
  );
}

🎯 Examples

E-commerce App

const ecommerceItems = [
  { id: 'home', icon: Home, label: 'Home', href: '/' },
  { id: 'products', icon: Package, label: 'Products', href: '/products' },
  { id: 'cart', icon: ShoppingCart, label: 'Cart', href: '/cart' },
  { id: 'orders', icon: Receipt, label: 'Orders', href: '/orders' },
];

<FloatingNavigation items={ecommerceItems} />

Admin Dashboard

const adminItems = [
  { id: 'dashboard', icon: BarChart3, label: 'Dashboard', href: '/admin' },
  { id: 'users', icon: Users, label: 'Users', href: '/admin/users' },
  { id: 'settings', icon: Settings, label: 'Settings', href: '/admin/settings' },
  { id: 'analytics', icon: TrendingUp, label: 'Analytics', href: '/admin/analytics' },
];

<FloatingNavigation items={adminItems} position="right" />

🧪 Testing

The component includes built-in accessibility features and can be tested using standard React testing libraries:

import { render, screen } from '@testing-library/react';
import { FloatingNavigation } from '@pmcs/floating-navigation';

test('renders navigation items', () => {
  render(<FloatingNavigation />);
  
  expect(screen.getByLabelText('Home')).toBeInTheDocument();
  expect(screen.getByLabelText('Projects')).toBeInTheDocument();
});

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT © Alexandros Liaskos