🚀 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

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

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

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

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:

<ng-mlpm [title]="'My Application'" [titleIcon]="'menu'" [menuItems]="menuItems" (linkClick)="onMenuItemClick($event)">
</ng-mlpm>

5. Customize the Theme (Optional)

You can customize the appearance by providing a color theme:

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:

<ng-mlpm
  [title]="'My Application'"
  [titleIcon]="'menu'"
  [menuItems]="menuItems"
  [colorTheme]="customTheme"
  (linkClick)="onMenuItemClick($event)">
</ng-mlpm>

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:

<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet" />

2. Use icon names from the Material Icons library in your menu items:

menuItems = [
  {
    label: 'Dashboard',
    icon: 'dashboard', // Material icon name
    link: '/dashboard',
  },
  // ...
];

7. Handling Navigation

Implement navigation logic in your component:

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:

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:

<button (click)="toggleMenu()">Toggle Menu</button>
<!-- Or access directly via template ref: <button (click)="menu.toggle()">Toggle</button> -->

<ng-mlpm #menu [title]="'My Application'" [menuItems]="menuItems" (linkClick)="onMenuItemClick($event)"> </ng-mlpm>

📚 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

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:

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