NGX Horizontal Scroll Menu

🚀 Now compatible with Angular 19! Fully updated with 100% test coverage and modern Angular features.

Description

A lightweight, customizable Angular library for creating beautiful horizontal scrolling menus with smooth navigation controls. Perfect for navigation bars, category filters, or any horizontal list that needs elegant scrolling functionality.

✨ Key Benefits:

• 🎯 Zero Configuration - Works out of the box with sensible defaults
• 🎨 Fully Customizable - Style with your own CSS classes
• 📱 Responsive - Adapts to different screen sizes
• ⚡ Lightweight - Minimal bundle size impact
• 🔧 TypeScript Support - Full type safety included
• 🧪 100% Test Coverage - Production-ready reliability

🎯 Live Demo

Try it on StackBlitz →

✨ Features

• 📋 Dynamic Menu Items - Pass any array of objects as menu items
• 🔗 Smart Link Handling - Automatic link detection or custom click events
• 🎨 Custom Styling - Apply your own CSS classes for background and text
• 🏃‍♂️ Smooth Scrolling - Configurable scroll speed and distance
• 🎛️ Navigation Controls - Optional left/right arrow navigation
• 🖼️ Custom Icons - Use your own navigation arrow icons
• 📱 Touch Friendly - Works great on mobile devices
• ♿ Accessible - Keyboard navigation support

📦 Installation

npm install ngx-horizontal-scroll-menu --save

🚀 Quick Start

1. Import the Module

For Angular 19+ (Standalone Components - Recommended):

import { HorizontalScrollMenuComponent } from 'ngx-horizontal-scroll-menu';

@Component({
  standalone: true,
  imports: [HorizontalScrollMenuComponent],
  // ... your component
})
export class MyComponent { }

Alternative - Using the Module:

import { HorizontalScrollMenuModule } from 'ngx-horizontal-scroll-menu';

@Component({
  standalone: true,
  imports: [HorizontalScrollMenuModule],
  // ... your component
})
export class MyComponent { }

For NgModule-based Apps:

import { NgModule } from '@angular/core';
import { HorizontalScrollMenuModule } from 'ngx-horizontal-scroll-menu';

@NgModule({
  imports: [
    HorizontalScrollMenuModule
  ],
  declarations: [AppComponent],
  bootstrap: [AppComponent]
})
export class AppModule { }

2. Use in Your Template

Basic Usage:

import { Component } from '@angular/core';

@Component({
  selector: 'app-root',
  template: `
    <ngx-horizontal-scroll-menu
      [items]="menuItems"
      [linkLabel]="'url'"
      [background]="'bg-primary'"
      [text]="'text-white'">
    </ngx-horizontal-scroll-menu>
  `
})
export class AppComponent {
  menuItems = [
    { title: 'Home', url: '/home' },
    { title: 'Products', url: '/products' },
    { title: 'Services', url: '/services' },
    { title: 'About', url: '/about' },
    { title: 'Contact', url: '/contact' }
  ];
}

With Click Events (No Links):

@Component({
  template: `
    <ngx-horizontal-scroll-menu
      [items]="categories"
      (clickedEventEmiiter)="onCategoryClick($event)">
    </ngx-horizontal-scroll-menu>
  `
})
export class AppComponent {
  categories = [
    { title: 'Electronics', id: 1 },
    { title: 'Clothing', id: 2 },
    { title: 'Books', id: 3 },
    { title: 'Sports', id: 4 }
  ];

  onCategoryClick(category: any) {
    console.log('Selected category:', category);
    // Handle navigation programmatically
    this.router.navigate(['/category', category.id]);
  }
}

⚙️ API Reference

Input Properties

| Property | Type | Default | Description | |----------|------|---------|-------------| | items | any[] | [] | Array of menu items to display. Each item should have a title property | | linkLabel | string | 'link' | Property name in items that contains the URL. Omit for click events only | | background | string | undefined | CSS class name for styling the menu background | | text | string | undefined | CSS class name for styling the menu item text | | distance | number | 50 | Scroll distance in pixels when using navigation arrows | | scrollSpeed | number | 100 | Scroll animation speed in milliseconds (for mousedown events) | | hideNav | boolean | false | Hide the left/right navigation arrows | | leftIcon | string | Base64 arrow | Custom icon for navigation arrows (24px recommended) | | navIcon | ImageModel | undefined | Custom navigation icon configuration |

Output Events

| Event | Type | Description | |-------|------|-------------| | clickedEventEmiiter | EventEmitter<any> | Emitted when a menu item is clicked. Returns the clicked item object |

ImageModel Interface

interface ImageModel {
  type: string;    // Image type (e.g., 'png', 'svg')
  image: string;   // Image URL or base64 data
}

🎨 Styling Examples

Bootstrap Classes:

<ngx-horizontal-scroll-menu
  [items]="items"
  [background]="'bg-dark'"
  [text]="'text-light fw-bold'">
</ngx-horizontal-scroll-menu>

Custom CSS Classes:

.custom-menu-bg {
  background: linear-gradient(45deg, #667eea 0%, #764ba2 100%);
  border-radius: 10px;
  padding: 10px;
}

.custom-menu-text {
  color: white;
  font-weight: 600;
  text-transform: uppercase;
}

🔧 Advanced Configuration

Custom Scroll Behavior:

<ngx-horizontal-scroll-menu
  [items]="items"
  [distance]="100"
  [scrollSpeed]="50"
  [hideNav]="false">
</ngx-horizontal-scroll-menu>

🗺️ Roadmap

• [ ] Virtual Scrolling - Handle thousands of items efficiently
• [ ] Keyboard Navigation - Arrow key support
• [ ] RTL Support - Right-to-left language support
• [ ] Accessibility Improvements - Enhanced ARIA support
• [ ] Animation Presets - Pre-built scroll animations
• [ ] Icon Customization - More flexible icon system

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

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

📄 License

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

👨‍💻 Author

Isah Ohieku

• GitHub: @isahohieku
• Twitter: @isahohieku

⭐ If this library helped you, please give it a star! ⭐