ngx-horizontal-scroll-menu

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.

• Fork the repository
• Create your feature branch (git checkout -b feature/AmazingFeature)
• Commit your changes (git commit -m 'Add some AmazingFeature')
• Push to the branch (git push origin feature/AmazingFeature)
• 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! ⭐