🚀 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 = {
    primary: '#2c3e50',
    secondary: '#34495e',
    text: '#ecf0f1',
    accent: '#3498db',
    hover: '#3e5871'
  };
}

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 } from "@angular/core";
import { MlpmComponent } from "@ramiz4/ng-mlpm";

@Component({
  // ...
})
export class YourComponent {
  // ...menu items

  isMenuVisible = false;

  toggleMenu() {
    this.isMenuVisible = !this.isMenuVisible;
  }
}

In your template:

<button (click)="toggleMenu()">Toggle Menu</button>

<ng-mlpm *ngIf="isMenuVisible" [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

Interfaces

interface MenuItem {
  label: string;
  icon?: string;
  link?: string;
  children?: MenuItem[];
}

interface MenuColorTheme {
  primary: string;
  secondary: string;
  text: string;
  accent: string;
  hover: 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.