🚀 ASafariM NavLinks

Dynamic Navigation Links with Multi-Level Dropdowns and Icons for React Apps

A versatile and feature-rich React component for creating dynamic navigation bars with unlimited multi-level dropdown menus, icons, emojis, and flexible styling options. Perfect for modern web applications that require sophisticated navigation structures.

🎯 Features

• ✅ Unlimited Multi-level Dropdown Menus - Create deeply nested navigation structures with unlimited submenus that open on hover
• ✅ Four Alignment Options - Left, right, top, and bottom positioning for flexible dropdown placement
• ✅ Icon Support - Font Awesome icons on left/right sides of menu items
• ✅ Emoji Support - Modern emoji indicators for visually engaging navigation
• ✅ SVG/Logo Integration - Custom logos and SVG icons for brand identity
• ✅ TypeScript Support - Full type definitions included for developer productivity
• ✅ Customizable Styling - Extensive CSS classes and inline style options for perfect UI integration
• ✅ Mobile Responsive Design - Automatic mobile detection with hamburger menu, animated cross icon, and touch-friendly navigation
• ✅ Zero Dependencies - Lightweight and efficient, no external dependencies
• ✅ Accessible - Built with accessibility in mind for all users

🚀 Live Demo

🎮 Interactive Online Demo - Experience all features in action directly in your browser!

1# Run the demo locally
2pnpm run demo

🔍 Demo Highlights

• Deep Nesting: See multi-level dropdown menus in action (5+ levels deep)
• Four Alignment Options: Left, right, top, and bottom dropdown positioning
• Interactive Examples: Try different navigation styles and configurations
• Code Samples: Ready-to-use code snippets for each feature
• Visual Guide: Clear visualization of all component capabilities

Multi-level dropdown menus with unlimited nesting support

Four different alignment options for dropdown positioning

📦 Installation

1# npm
2npm install asafarim-navlinks
3
4# yarn
5yarn add asafarim-navlinks
6
7# pnpm
8pnpm add asafarim-navlinks

🎪 Quick Start

1import React from 'react';
2import NavLinks, { NavLinkType } from 'asafarim-navlinks';
3
4const navData: NavLinkType[] = [
5  {
6    label: 'Home',
7    href: '/',
8    iconLeft: 'fas fa-home'
9  },
10  {
11    label: 'Products',
12    href: '/products',
13    iconLeft: 'fas fa-box',
14    subNav: [
15      { label: 'Web Apps', href: '/web-apps' },
16      { label: 'Mobile Apps', href: '/mobile-apps' }
17    ]
18  },
19  {
20    label: 'About',
21    href: '/about',
22    emoji: '📖'
23  }
24];
25
26function App() {
27  return (
28    <nav>
29      <NavLinks links={navData} />
30    </nav>
31  );
32}

🎨 Examples

Basic Navigation

1const basicLinks: NavLinkType[] = [
2  { label: 'Home', href: '/' },
3  { label: 'About', href: '/about' },
4  { label: 'Contact', href: '/contact' }
5];
6
7<NavLinks links={basicLinks} />

Multi-level Dropdown Menus

1const nestedLinks: NavLinkType[] = [
2  { 
3    label: 'Products', 
4    href: '/products',
5    subNav: [
6      { label: 'Software', href: '/software' },
7      { 
8        label: 'Services', 
9        href: '/services',
10        subNav: [
11          { 
12            label: 'Consulting', 
13            href: '/consulting',
14            subNav: [
15              { label: 'Technical', href: '/technical' },
16              { label: 'Business', href: '/business' }
17            ]
18          },
19          { label: 'Training', href: '/training' }
20        ]
21      }
22    ]
23  }
24];
25
26<NavLinks links={nestedLinks} />

With Icons

1const iconLinks: NavLinkType[] = [
2  { label: 'Dashboard', href: '/dashboard', iconLeft: 'fas fa-tachometer-alt' },
3  { label: 'Settings', href: '/settings', iconRight: 'fas fa-cog' },
4  { label: 'Profile', href: '/profile', iconLeft: 'fas fa-user' }
5];
6
7<NavLinks links={iconLinks} />

With Emojis

1const emojiLinks: NavLinkType[] = [
2  { label: 'Home', href: '/', emoji: '🏠' },
3  { label: 'Products', href: '/products', emoji: '📦' },
4  { label: 'Support', href: '/support', emoji: '🎧' }
5];
6
7<NavLinks links={emojiLinks} />

Multi-level Dropdowns

1const dropdownLinks: NavLinkType[] = [
2  {
3    label: 'Services',
4    href: '/services',
5    iconLeft: 'fas fa-concierge-bell',
6    subNav: [
7      { label: 'Web Development', href: '/web-dev' },
8      {
9        label: 'Support',
10        href: '/support',
11        subNav: [
12          { label: '24/7 Support', href: '/support-24-7' },
13          { label: 'Documentation', href: '/docs' },
14          { label: 'Community', href: '/community' }
15        ]
16      },
17      { label: 'Consulting', href: '/consulting' }
18    ]
19  }
20];
21
22<NavLinks links={dropdownLinks} />

With Custom Logo

1const logoLinks: NavLinkType[] = [
2  {
3    label: 'Brand',
4    href: '/',
5    svgLogoIcon: {
6      src: '/logo.svg',
7      alt: 'Company Logo',
8      width: 40,
9      height: 40,
10      caption: 'MyBrand'
11    }
12  },
13  { label: 'Products', href: '/products' }
14];
15
16<NavLinks links={logoLinks} />

Mobile Responsive Navigation

1// Automatic mobile detection and responsive behavior
2<NavLinks 
3  links={mobileNavLinks}
4  baseLinkStyle={{ 
5    display: 'flex',
6    flexWrap: 'wrap' // Allows wrapping on smaller screens
7  }}
8/>
9
10// With collapsible mobile menu (hamburger menu)
11<NavLinks 
12  links={mobileNavLinks}
13  enableMobileCollapse={true}
14/>
15
16// Force mobile behavior for testing
17<NavLinks 
18  links={mobileNavLinks}
19  isMobile={true}
20  enableMobileCollapse={true}
21/>

Mobile Features:

• Automatic Detection: Responsive breakpoint at 768px with automatic hamburger menu
• Smart Behavior: Hamburger menu appears automatically on mobile devices
• Animated Cross Icon: Professional hamburger-to-cross animation when menu opens
• Touch-Friendly: Larger touch targets and proper spacing
• Collapsible Menu: Hamburger menu automatically enabled on mobile screens
• Vertical Stacking: Navigation items stack vertically on mobile
• Simplified Dropdowns: Dropdowns appear below instead of to the side

Mobile Responsive Examples

Automatic Mobile Detection (Recommended)

1// Automatically shows hamburger menu on mobile devices
2<NavLinks 
3  links={mobileNavLinks}
4  baseLinkStyle={{ 
5    display: 'flex',
6    gap: '20px' // Adjusts automatically for mobile
7  }}
8/>

Manual Mobile Control

1// Force mobile behavior for testing
2<NavLinks 
3  links={mobileNavLinks}
4  isMobile={true}
5  enableMobileCollapse={true}
6/>
7
8// Disable mobile collapse even on mobile
9<NavLinks 
10  links={mobileNavLinks}
11  enableMobileCollapse={false}
12/>

📝 Component Props

NavLinks Component

Prop	Type	Default	Description
links	NavLinkType[]	Required	Array of navigation link objects
className	string	undefined	Custom CSS class for the navigation container
baseLinkStyle	React.CSSProperties	undefined	Inline styles for top-level links
subLinkStyle	React.CSSProperties	undefined	Inline styles for dropdown links
isRightAligned	boolean	false	Right-align the dropdown menus
isLeftAligned	boolean	false	Left-align the dropdown menus (nested dropdowns appear to the left)
isBottomAligned	boolean	false	Position dropdowns below their parent items (default behavior)
isTopAligned	boolean	false	Position dropdowns above their parent items
isMobile	boolean	false	Force mobile behavior regardless of screen size
enableMobileCollapse	boolean	false	Enable collapsible hamburger menu on mobile. Note: Hamburger menu automatically appears on mobile devices (≤768px) regardless of this setting

NavLinkType Interface

1interface NavLinkType {
2  label?: string;          // Text label for the link
3  title?: string;          // Title attribute (tooltip)
4  href: string;            // URL for the link
5  iconLeft?: string;       // Font Awesome class for left icon
6  iconRight?: string;      // Font Awesome class for right icon
7  emoji?: string;          // Emoji character
8  subNav?: NavLinkType[];  // Array of sub-navigation items
9  svgLogoIcon?: {          // Custom SVG/logo configuration
10    src: string;
11    alt: string;
12    width?: number;
13    height?: number | string;
14    caption?: string;
15    style?: React.CSSProperties;
16  };
17}

🎨 Styling and Customization

CSS Customization

The component uses CSS modules with default styling that can be easily overridden:

1/* In your CSS file */
2.custom-nav ul li a {
3  color: #3498db !important;
4  font-weight: bold;
5}
6
7.custom-nav ul ul {
8  background: linear-gradient(135deg, #2c3e50 0%, #34495e 100%) !important;
9}

1<NavLinks 
2  links={links} 
3  className="custom-nav"
4/>

Inline Styling

You can apply inline styles directly to the component:

1<NavLinks 
2  links={links}
3  baseLinkStyle={{ 
4    fontSize: '16px', 
5    fontWeight: 'bold',
6    padding: '12px 16px'
7  }}
8  subLinkStyle={{
9    backgroundColor: '#2c3e50',
10    minWidth: '220px'
11  }}
12/>

Responsive Design

The component is built with responsive design in mind. You can further enhance responsiveness with your own CSS:

1@media (max-width: 768px) {
2  .custom-nav ul li {
3    display: block;
4    width: 100%;
5  }
6  
7  .custom-nav ul ul {
8    position: static;
9    display: none;
10  }
11}

🌟 Advanced Usage

Dropdown Behavior

All dropdowns are hidden by default and only appear when hovering over their parent item. This behavior works consistently across all nesting levels:

1const advancedNav: NavLinkType[] = [
2  {
3    label: 'Resources',
4    href: '#',
5    subNav: [
6      {
7        label: 'Documentation',
8        href: '/docs',
9        subNav: [
10          {
11            label: 'Components',
12            href: '/docs/components',
13            subNav: [
14              // This will appear when hovering on "Components"
15              { label: 'Navigation', href: '/docs/components/navigation' }
16            ]
17          }
18        ]
19      }
20    ]
21  }
22];

Alignment Options

The component supports four different alignment options for dropdown positioning:

Left-Aligned Navigation (Default)

1<NavLinks 
2  links={navData}
3  isLeftAligned={true}
4/>

Right-Aligned Navigation

1<NavLinks 
2  links={navData}
3  isRightAligned={true}
4  baseLinkStyle={{ justifyContent: 'flex-end' }}
5/>

Top-Aligned Navigation

1<NavLinks 
2  links={navData}
3  isTopAligned={true}
4/>

Bottom-Aligned Navigation (Default)

1<NavLinks 
2  links={navData}
3  isBottomAligned={true}
4/>

Combined Alignment Options

You can combine horizontal and vertical alignment for custom positioning:

1// Dropdowns appear above and slide to the right
2<NavLinks 
3  links={navLinks} 
4  isTopAligned={true} 
5  isRightAligned={true} 
6/>
7
8// Dropdowns appear below and slide to the left  
9<NavLinks 
10  links={navLinks} 
11  isBottomAligned={true} 
12  isLeftAligned={true} 
13/>

Complex Navigation Layout

1function Navigation() {
2  const leftLinks = [
3    { label: 'Home', href: '/', iconLeft: 'fas fa-home' }
4  ];
5  
6  const rightLinks = [
7    { label: 'Login', href: '/login', iconRight: 'fas fa-sign-in-alt' }
8  ];
9
10  return (
11    <nav style={{ display: 'flex', justifyContent: 'space-between' }}>
12      <NavLinks links={leftLinks} />
13      <NavLinks links={rightLinks} isRightAligned={true} />
14    </nav>
15  );
16}

All Alignment Options

1const alignmentLinks: NavLinkType[] = [
2  {
3    label: 'Services',
4    href: '#services',
5    subNav: [
6      { label: 'Web Design', href: '#web-design' },
7      { label: 'Development', href: '#development' }
8    ]
9  }
10];
11
12// Left aligned - nested dropdowns appear to the left (default)
13<NavLinks links={alignmentLinks} isLeftAligned={true} />
14
15// Right aligned - nested dropdowns appear to the right
16<NavLinks links={alignmentLinks} isRightAligned={true} />
17
18// Top aligned - dropdowns appear above parent items
19<NavLinks links={alignmentLinks} isTopAligned={true} />
20
21// Bottom aligned - dropdowns appear below parent items (default)
22<NavLinks links={alignmentLinks} isBottomAligned={true} />

Dropdown Behavior

All dropdowns are hidden by default and only appear when hovering over their parent item. This behavior works consistently across all nesting levels:

1const advancedNav: NavLinkType[] = [
2  {
3    label: 'Resources',
4    href: '#',
5    subNav: [
6      {
7        label: 'Documentation',
8        href: '/docs',
9        subNav: [
10          {
11            label: 'Components',
12            href: '/docs/components',
13            subNav: [
14              // This will appear when hovering on "Components"
15              { label: 'Navigation', href: '/docs/components/navigation' }
16            ]
17          }
18        ]
19      }
20    ]
21  }
22];

📖 Full Example

1import React from 'react';
2import NavLinks, { NavLinkType } from 'asafarim-navlinks';
3
4const navigationData: NavLinkType[] = [
5  {
6    label: 'Home',
7    href: '/',
8    svgLogoIcon: {
9      src: '/logo.svg',
10      alt: 'Company Logo',
11      width: 30,
12      height: 30,
13      caption: 'MyApp'
14    }
15  },
16  {
17    label: 'Products',
18    href: '/products',
19    iconLeft: 'fas fa-cube',
20    subNav: [
21      { label: 'Web Applications', href: '/web-apps', emoji: '🌐' },
22      { label: 'Mobile Apps', href: '/mobile-apps', emoji: '📱' },
23      {
24        label: 'Enterprise Solutions',
25        href: '/enterprise',
26        emoji: '🏢',
27        subNav: [
28          { label: 'CRM Systems', href: '/crm' },
29          { label: 'ERP Solutions', href: '/erp' },
30          { label: 'Custom Development', href: '/custom' }
31        ]
32      }
33    ]
34  },
35  {
36    label: 'Services',
37    href: '/services',
38    iconLeft: 'fas fa-concierge-bell',
39    subNav: [
40      { label: 'Consulting', href: '/consulting' },
41      { label: 'Support', href: '/support' },
42      { label: 'Training', href: '/training' }
43    ]
44  },
45  {
46    label: 'About',
47    href: '/about',
48    iconLeft: 'fas fa-info-circle'
49  },
50  {
51    label: 'Contact',
52    href: '/contact',
53    iconLeft: 'fas fa-envelope'
54  }
55];
56
57function App() {
58  return (
59    <div className="app">
60      <header className="header">
61        <nav className="navigation">
62          <NavLinks 
63            links={navigationData}
64            baseLinkStyle={{
65              display: 'flex',
66              gap: '1rem',
67              listStyle: 'none',
68              margin: 0,
69              padding: 0
70            }}
71            subLinkStyle={{
72              backgroundColor: '#2c3e50',
73              padding: '0.5rem',
74              borderRadius: '4px',
75              minWidth: '200px'
76            }}
77          />
78        </nav>
79      </header>
80      <main className="main-content">
81        <h1>Welcome to My App</h1>
82      </main>
83    </div>
84  );
85}
86
87export default App;

🛠️ Development

Setup

1# Clone the repository
2git clone https://github.com/AliSafari-IT/asafarim-navlinks.git
3
4# Install dependencies
5pnpm install
6
7# Build the package
8pnpm run build
9
10# Run the demo
11pnpm run demo

Scripts

1pnpm run build          # Build the package
2pnpm run demo           # Run the demo
3pnpm run demo:install   # Install demo dependencies
4pnpm run demo:build     # Build the demo
5pnpm run publishPublicly # Publish to npm

👥 Contributing

Contributions are welcome! Here's how you can contribute:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please make sure to update tests as appropriate.

📄 License

This project is licensed under the MIT License - see the MIT_License file for details.

👨‍💻 Author

Ali Safari - @AliSafari-IT

---

Made with ❤️ for the React community

⚠️ Troubleshooting

Dropdowns Not Opening on Hover

If your dropdowns aren't opening on hover, check:

1. Make sure there are no CSS conflicts in your project overriding the hover behavior
2. Verify that your navigation data structure is correct with properly nested subNav arrays
3. Try increasing the CSS specificity in your custom styles with !important flags

Dropdown Positioning Issues

If your dropdowns are not positioned correctly:

1. Check if alignment props (isLeftAligned, isRightAligned, isTopAligned, isBottomAligned) need to be adjusted
2. Ensure the parent container has position: relative
3. Add higher z-index values if dropdowns are appearing behind other elements
4. For edge cases, consider combining alignment options (e.g., isTopAligned={true} with isRightAligned={true})

SVG/Logo Image Loading

If SVG or logo images aren't loading:

1. Verify the image path is correct and accessible
2. Check that the SVG file is properly formatted
3. Try using an absolute URL path if using a relative path doesn't work

Mobile Support

For better mobile support:

1. Implement a responsive design with CSS media queries
2. Consider adding touch support for mobile devices with additional CSS/JS
3. Test on various device sizes and orientations