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

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

🚀 Quick Start

$3

For Angular 19+ (Standalone Components - Recommended):
`typescript
import { HorizontalScrollMenuComponent } from 'ngx-horizontal-scroll-menu';

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

Alternative - Using the Module:
`typescript
import { HorizontalScrollMenuModule } from 'ngx-horizontal-scroll-menu';

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

For NgModule-based Apps:
`typescript
import { NgModule } from '@angular/core';
import { HorizontalScrollMenuModule } from 'ngx-horizontal-scroll-menu';

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

$3

Basic Usage:
`typescript
import { Component } from '@angular/core';

@Component({
selector: 'app-root',
template:
[items]="menuItems"
[linkLabel]="'url'"
[background]="'bg-primary'"
[text]="'text-white'">


})
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):
`typescript
@Component({
template:
[items]="categories"
(clickedEventEmiiter)="onCategoryClick($event)">


})
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

$3

| 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 |

$3

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

$3

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

🎨 Styling Examples

Bootstrap Classes:
`html
[items]="items"
[background]="'bg-dark'"
[text]="'text-light fw-bold'">

`

Custom CSS Classes:
`css
.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:
`html
[items]="items"
[distance]="100"
[scrollSpeed]="50"
[hideNav]="false">

`

🗺️ 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! ⭐