NgSidebarPro

🚀 Professional, responsive and highly customizable sidebar component for Angular 17+ applications with Material Design 3 support.

✨ Features

• 📱 Fully Responsive - Auto-adapts to mobile, tablet, and desktop
• 🎨 4 Built-in Themes - Light, Dark, Corporate, Modern + Custom themes
• 🔧 Highly Configurable - Every aspect can be customized
• 🌟 Material Design 3 - Latest Material Design standards
• ⚡ Performance Optimized - Built with Angular Signals
• 🎯 TypeScript - Fully typed for better DX
• ♿ Accessible - WCAG 2.1 compliant
• 📱 Mobile First - Touch gestures and overlay support
• 🎭 Multi-level Menus - Unlimited nesting with animations
• 💾 State Persistence - Remembers user preferences

📸 Preview

| Desktop | Mobile | Dark Theme | |---------|--------|------------| | | | |

🚀 Quick Start

Installation

npm install ng-sidebar-pro

Peer Dependencies

npm install @angular/material @angular/cdk @angular/animations

Basic Setup

1. Import the module in your app:

// app.config.ts
import { ApplicationConfig, importProvidersFrom } from '@angular/core';
import { provideAnimations } from '@angular/platform-browser/animations';
import { SidebarModule } from 'ng-sidebar-pro';

export const appConfig: ApplicationConfig = {
  providers: [
    provideAnimations(),
    importProvidersFrom(
      SidebarModule.forRoot({
        theme: 'modern',
        width: { expanded: 280, collapsed: 60 },
        persistState: true
      })
    ),
    // ... other providers
  ]
};

2. Add to your component:

// app.component.ts
import { Component, signal, computed, inject } from '@angular/core';
import { SidebarComponent, SidebarMenuItem, SidebarConfigService } from 'ng-sidebar-pro';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [SidebarComponent],
  template: `
    <lib-sidebar [menuItems]="menuItems" [config]="sidebarConfig"></lib-sidebar>
    
    <main class="main-content" [style.margin-left.px]="contentMargin()">
      <router-outlet></router-outlet>
    </main>
  `,
  styles: [`
    .main-content {
      transition: margin-left 300ms ease;
      padding: 20px;
      min-height: 100vh;
    }
    
    @media (max-width: 768px) {
      .main-content {
        margin-left: 0 !important;
      }
    }
  `]
})
export class AppComponent {
  private sidebarService = inject(SidebarConfigService);
  
  menuItems = signal<SidebarMenuItem[]>([
    {
      id: 'dashboard',
      label: 'Dashboard',
      icon: 'dashboard',
      route: '/dashboard'
    },
    {
      id: 'users',
      label: 'Users',
      icon: 'people',
      badge: { text: '5', color: '#f44336' },
      children: [
        {
          id: 'users-list',
          label: 'User List',
          route: '/users/list'
        },
        {
          id: 'users-roles',
          label: 'Roles',
          route: '/users/roles'
        }
      ]
    },
    {
      id: 'settings',
      label: 'Settings',
      icon: 'settings',
      route: '/settings'
    }
  ]);
  
  sidebarConfig = {
    theme: 'modern' as const,
    header: {
      show: true,
      title: 'My App',
      subtitle: 'Dashboard'
    }
  };
  
  contentMargin = computed(() => {
    const state = this.sidebarService.state();
    const config = this.sidebarService.config();
    
    if (state.mobile) return 0;
    return state.collapsed ? config.width.collapsed : config.width.expanded;
  });
}

3. Add Material Icons (if not already added):

<!-- In your index.html -->
<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">

🎨 Themes

Built-in Themes

// Available themes
type Theme = 'light' | 'dark' | 'corporate' | 'modern' | 'auto' | 'custom';

// Usage
const config = {
  theme: 'dark', // Auto dark mode support
  // ... other options
};

Custom Theme

const customTheme = {
  theme: 'custom',
  customTheme: {
    primary: '#6366f1',
    secondary: '#ec4899',
    background: '#ffffff',
    surface: '#f8fafc',
    text: {
      primary: '#0f172a',
      secondary: '#64748b'
    }
  }
};

📱 Responsive Behavior

| Screen Size | Behavior | |-------------|----------| | Mobile (≤768px) | Overlay mode with backdrop, touch gestures | | Tablet (769-1024px) | Collapsible, auto-collapse option | | Desktop (≥1025px) | Fixed sidebar, full functionality |

Responsive Configuration

const responsiveConfig = {
  breakpoints: {
    mobile: 768,
    tablet: 1024,
    desktop: 1200
  },
  autoCollapse: true,  // Auto-collapse on tablet
  overlay: true,       // Enable overlay on mobile
  persistState: true   // Remember user preferences
};

⚙️ Configuration

Complete Configuration Interface

interface SidebarConfig {
  // Dimensions
  width: {
    expanded: number;     // Default: 280
    collapsed: number;    // Default: 60
  };
  
  // Behavior
  collapsible: boolean;        // Default: true
  autoCollapse: boolean;       // Default: false
  overlay: boolean;            // Default: true
  persistState: boolean;       // Default: true
  animationDuration: number;   // Default: 300
  
  // Appearance
  theme: 'light' | 'dark' | 'auto' | 'custom' | 'corporate' | 'modern';
  customTheme?: Partial<SidebarTheme>;
  borderRadius: number;        // Default: 8
  elevation: number;           // Default: 2
  
  // Header
  header: {
    show: boolean;             // Default: true
    height: number;            // Default: 80
    logo?: string;
    title?: string;
    subtitle?: string;
  };
  
  // Footer
  footer: {
    show: boolean;             // Default: false
    height: number;            // Default: 60
    content?: string;
  };
  
  // Responsive
  breakpoints: {
    mobile: number;            // Default: 768
    tablet: number;            // Default: 1024
    desktop: number;           // Default: 1200
  };
}

Menu Item Interface

interface SidebarMenuItem {
  id: string;                    // Required: Unique identifier
  label: string;                 // Required: Display text
  icon?: string;                 // Material icon name
  route?: string;                // Angular route
  badge?: {                      // Notification badge
    text: string;
    color: string;
  };
  disabled?: boolean;            // Disable item
  hidden?: boolean;              // Hide item
  divider?: boolean;             // Show divider after item
  children?: SidebarMenuItem[];  // Nested items
  metadata?: Record<string, any>; // Custom data
}

🎯 Advanced Usage

Service Integration

import { SidebarConfigService } from 'ng-sidebar-pro';

@Component({...})
export class MyComponent {
  private sidebarService = inject(SidebarConfigService);
  
  // Toggle sidebar
  toggleSidebar() {
    this.sidebarService.toggle();
  }
  
  // Change theme dynamically
  setDarkMode() {
    this.sidebarService.updateConfig({ theme: 'dark' });
  }
  
  // Listen to state changes
  ngOnInit() {
    effect(() => {
      const state = this.sidebarService.state();
      console.log('Sidebar state:', state);
    });
  }
}

Custom Header/Footer

@Component({
  template: `
    <lib-sidebar [menuItems]="menuItems">
      <!-- Custom header content -->
      <div slot="header">
        <img src="/logo.png" alt="Logo">
        <h2>Custom Header</h2>
      </div>
      
      <!-- Custom footer content -->
      <div slot="footer">
        <button mat-button (click)="logout()">
          <mat-icon>logout</mat-icon>
          Logout
        </button>
      </div>
    </lib-sidebar>
  `
})

Dynamic Menu Updates

export class DynamicMenuComponent {
  menuItems = signal<SidebarMenuItem[]>([]);
  
  async loadUserMenu() {
    const userRole = await this.authService.getUserRole();
    const menuItems = await this.menuService.getMenuForRole(userRole);
    this.menuItems.set(menuItems);
  }
  
  addNotificationBadge(itemId: string, count: number) {
    this.menuItems.update(items => 
      items.map(item => 
        item.id === itemId 
          ? { ...item, badge: { text: count.toString(), color: '#f44336' }}
          : item
      )
    );
  }
}

📖 Examples

E-commerce Dashboard

const ecommerceMenu: SidebarMenuItem[] = [
  {
    id: 'dashboard',
    label: 'Dashboard',
    icon: 'dashboard',
    route: '/dashboard'
  },
  {
    id: 'products',
    label: 'Products',
    icon: 'inventory',
    children: [
      { id: 'products-list', label: 'Product List', route: '/products' },
      { id: 'categories', label: 'Categories', route: '/categories' },
      { id: 'inventory', label: 'Inventory', route: '/inventory' }
    ]
  },
  {
    id: 'orders',
    label: 'Orders',
    icon: 'shopping_cart',
    badge: { text: '12', color: '#ff9800' },
    children: [
      { id: 'pending', label: 'Pending', route: '/orders/pending' },
      { id: 'completed', label: 'Completed', route: '/orders/completed' }
    ]
  },
  {
    id: 'customers',
    label: 'Customers',
    icon: 'people',
    route: '/customers'
  },
  {
    id: 'analytics',
    label: 'Analytics',
    icon: 'analytics',
    route: '/analytics'
  }
];

Corporate Application

const corporateConfig = {
  theme: 'corporate',
  width: { expanded: 300, collapsed: 70 },
  header: {
    show: true,
    title: 'Enterprise Portal',
    subtitle: 'Admin Dashboard',
    logo: '/assets/company-logo.png'
  },
  footer: {
    show: true,
    content: '© 2024 Company Name'
  }
};

🔧 Development

Building from Source

# Clone repository
git clone https://github.com/your-org/ng-sidebar-pro.git
cd ng-sidebar-pro

# Install dependencies
npm install

# Build library
npm run build

# Run tests
npm run test

# Serve demo app
npm start

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📋 Requirements

• Angular: 17.0.0 or higher
• Angular Material: 17.0.0 or higher
• TypeScript: 5.0.0 or higher
• Node.js: 18.0.0 or higher

🌟 Browser Support

| Browser | Version | |---------|---------| | Chrome | 90+ | | Firefox | 88+ | | Safari | 14+ | | Edge | 90+ |

📚 Documentation

• 📖 Full Documentation
• 🎨 Theme Customization Guide
• 📱 Responsive Design Guide
• ⚡ Performance Tips
• ♿ Accessibility Guide

🔗 Links

• Demo Application
• Stackblitz Example
• GitHub Repository
• Issue Tracker
• Changelog

🆘 Support

• 📧 Email: [email protected]
• 💬 Discord: Join our community
• 🐛 Issues: GitHub Issues
• 📚 Stack Overflow: Tag with ng-sidebar-pro

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Angular Team for the amazing framework
• Material Design Team for design guidelines
• Contributors and community feedback

Made with ❤️ for the Angular community

⭐ Star us on GitHub • 🐦 Follow on Twitter • 📺 Subscribe on YouTube