https://github.com/ramiz4/ng-mlpm
An elegant, highly customizable multilevel progressive menu component library for Angular applications
https://github.com/ramiz4/ng-mlpm
angular component-library menu menu-navigation navigation typescript
Last synced: 5 months ago
JSON representation
An elegant, highly customizable multilevel progressive menu component library for Angular applications
- Host: GitHub
- URL: https://github.com/ramiz4/ng-mlpm
- Owner: ramiz4
- Created: 2025-05-05T09:50:55.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-11-13T13:20:29.000Z (7 months ago)
- Last Synced: 2025-11-13T15:18:18.874Z (7 months ago)
- Topics: angular, component-library, menu, menu-navigation, navigation, typescript
- Language: TypeScript
- Homepage: https://ramiz4.github.io/ng-mlpm/
- Size: 1.93 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 🚀 NgMlpm - Angular Multilevel Progressive Menu
## ✨ Overview
**NgMlpm** is an elegant, highly customizable multilevel progressive menu component library for Angular applications. It provides a smooth user experience for navigating complex menu hierarchies with animated transitions and a responsive design.
## 🔥 Live Demo
Experience the component in action: [Live Demo](https://ramiz4.github.io/ng-mlpm)
## 🎨 Features
- **Hierarchical Navigation** - Seamlessly navigate through nested menu structures
- **Smooth Animations** - Enjoy fluid transitions between menu levels
- **Customizable Themes** - Easily adapt the menu to match your application's design system
- **Icon Support** - Integrate icons for enhanced visual navigation
- **Responsive Design** - Works beautifully across all device sizes
- **Standalone Components** - Built with Angular's latest standalone component architecture
- **Lightweight** - Minimal footprint for optimal performance
## 📋 Step-by-Step Usage Guide
### 1. Installation
Install the package using your preferred package manager:
```bash
# Using npm
npm install @ramiz4/ng-mlpm
# Using pnpm
pnpm add @ramiz4/ng-mlpm
# Using yarn
yarn add @ramiz4/ng-mlpm
```
### 2. Import the Component
Add the MlpmComponent to your standalone component or NgModule:
```typescript
// In a standalone component
import { Component } from '@angular/core';
import { MlpmComponent } from '@ramiz4/ng-mlpm';
@Component({
selector: 'app-my-component',
standalone: true,
imports: [MlpmComponent],
// ...
})
export class MyComponent {
// Component logic
}
// OR in a module
import { NgModule } from '@angular/core';
import { MlpmComponent } from '@ramiz4/ng-mlpm';
@NgModule({
imports: [
// ...other imports
MlpmComponent,
],
// ...
})
export class MyModule {}
```
### 3. Define Menu Items
Create a menu structure in your component:
```typescript
import { Component } from '@angular/core';
import { MlpmComponent } from '@ramiz4/ng-mlpm';
import { MenuItem } from '@ramiz4/ng-mlpm'; // Import the interface
@Component({
// ...
imports: [MlpmComponent],
// ...
})
export class YourComponent {
// Define your menu structure
menuItems: MenuItem[] = [
{
label: 'Dashboard',
icon: 'dashboard',
link: '/dashboard',
},
{
label: 'Settings',
icon: 'settings',
children: [
{ label: 'Profile', icon: 'person', link: '/settings/profile' },
{ label: 'Preferences', icon: 'tune', link: '/settings/preferences' },
],
},
{
label: 'Reports',
icon: 'bar_chart',
children: [
{ label: 'Annual', icon: 'calendar_today', link: '/reports/annual' },
{ label: 'Monthly', icon: 'date_range', link: '/reports/monthly' },
{
label: 'Custom',
icon: 'tune',
children: [
{ label: 'By Region', icon: 'public', link: '/reports/custom/region' },
{ label: 'By Department', icon: 'people', link: '/reports/custom/department' },
],
},
],
},
];
// Handle menu item clicks
onMenuItemClick(item: MenuItem) {
console.log('Menu item clicked:', item);
// Add your navigation logic here
}
}
```
### 4. Add the Component to Your Template
Use the component in your HTML template:
```html
```
### 5. Customize the Theme (Optional)
You can customize the appearance by providing a color theme:
```typescript
import { Component } from '@angular/core';
import { MlpmComponent, MenuColorTheme } from '@ramiz4/ng-mlpm';
@Component({
// ...
})
export class YourComponent {
// ...menu items
// Define a custom theme
customTheme: MenuColorTheme = {
primaryBackground: '#2c3e50',
secondaryBackground: '#34495e',
tertiaryBackground: '#2c3e50',
primaryText: '#ecf0f1',
secondaryText: '#bdc3c7',
tertiaryText: '#95a5a6',
primaryAccent: '#3498db',
secondaryAccent: '#2980b9',
tertiaryAccent: '#1abc9c',
primaryHover: '#3e5871',
secondaryHover: '#2c3e50',
tertiaryHover: '#34495e',
};
}
```
Then apply it to the component:
```html
```
### 6. Using Icons
The component supports a variety of icons. By default, it uses Material Icons:
1. Add Material Icons to your project by including the following in your `index.html`:
```html
```
2. Use icon names from the Material Icons library in your menu items:
```typescript
menuItems = [
{
label: 'Dashboard',
icon: 'dashboard', // Material icon name
link: '/dashboard',
},
// ...
];
```
### 7. Handling Navigation
Implement navigation logic in your component:
```typescript
import { Component } from '@angular/core';
import { Router } from '@angular/router';
import { MlpmComponent, MenuItem } from '@ramiz4/ng-mlpm';
@Component({
// ...
imports: [MlpmComponent],
// ...
})
export class YourComponent {
// ...menu items
constructor(private router: Router) {}
onMenuItemClick(item: MenuItem) {
if (item.link) {
this.router.navigate([item.link]);
}
}
}
```
### 8. Responsive Behavior
The component is responsive by default. For mobile views, you might want to toggle its visibility:
```typescript
import { Component, ViewChild } from '@angular/core';
import { MlpmComponent } from '@ramiz4/ng-mlpm';
@Component({
// ...
})
export class YourComponent {
// ...menu items
@ViewChild(MlpmComponent) menu!: MlpmComponent;
toggleMenu() {
this.menu.toggle();
}
}
```
In your template:
```html
Toggle Menu
```
## 📚 API Reference
### Inputs
| Input | Type | Description | Default |
| ---------- | -------------- | ------------------------------------------ | ----------------- |
| title | string | The title displayed at the top of the menu | 'Menu' |
| titleIcon | string | Icon name for the title | 'menu' |
| menuItems | MenuItem[] | Array of menu items to display | [] |
| colorTheme | MenuColorTheme | Custom color theme for the menu | defaultColorTheme |
### Outputs
| Output | Type | Description |
| --------- | ---------------------- | ----------------------------------------------- |
| linkClick | EventEmitter | Emitted when a menu item with a link is clicked |
### Methods
| Method | Description |
| -------- | ---------------------------------------------------------------------- |
| toggle() | Toggles the collapsed state of the menu and triggers change detection. |
### Interfaces
```typescript
interface MenuItem {
label: string;
icon?: string;
link?: string;
children?: MenuItem[];
}
interface MenuColorTheme {
primaryBackground: string;
secondaryBackground: string;
tertiaryBackground: string;
primaryText: string;
secondaryText: string;
tertiaryText: string;
primaryAccent: string;
secondaryAccent: string;
tertiaryAccent: string;
primaryHover: string;
secondaryHover: string;
tertiaryHover: string;
}
```
## 🛠️ Development
To start a local development server, run:
```bash
# Using npm
npm start
# Using pnpm
pnpm start
```
Once the server is running, open your browser and navigate to `http://localhost:4200/`. The application will automatically reload whenever you modify any of the source files.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the MIT License - see the LICENSE file for details.