Installation

This guide covers everything you need to install and configure ng-magary in your Angular application.

Prerequisites: Ensure you have an Angular application (v17+) created. If starting fresh, use ng new my-app or npx @angular/cli new my-app.

Quick Install

Choose your preferred package manager:

npm install ng-magary @angular/cdk @angular/animations @atlaskit/pragmatic-drag-and-drop lucide lucide-angular gridstack

Recommended: Use pnpm for faster installs and better disk space efficiency.

Understanding Dependencies

Core Package

ng-magary (Core Library)

The main component library containing all UI components.Version: 0.0.22What’s Included:

50+ standalone Angular components
TypeScript type definitions
Component styles (scoped)
Theme service and utilities

Peer Dependencies

Magary requires several peer dependencies to function properly:

@angular/core, @angular/common (Required)

Version Range: ^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0 || ^21.0.0These are Angular’s core packages. They’re likely already installed in your project.

{
  "@angular/core": "^21.0.0",
  "@angular/common": "^21.0.0"
}

@angular/animations (Required)

Version Range: ^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0 || ^21.0.0Powers smooth transitions and animations in Magary components.Why Required: Magary components use Angular’s animation system for:

Dialog enter/exit transitions
Tooltip fade effects
Menu slide animations
Loading states

@angular/cdk (Required)

Version Range: ^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0 || ^21.0.0Angular Component Dev Kit provides foundational behaviors.What It Powers:

Overlay positioning (tooltips, dialogs, menus)
Accessibility features (a11y module)
Table virtual scrolling
Drag-and-drop foundations

@atlaskit/pragmatic-drag-and-drop (Required)

Version Range: >=1.7.0 <2High-performance drag-and-drop library from Atlassian.Used By:

MagaryKanban (kanban board)
MagaryPicklist (dual-list transfer)
MagaryOrderlist (reorderable lists)
MagaryTable (column reordering)

lucide & lucide-angular (Required)

Version Range: >=0.469.0 <1Beautiful, consistent icon library with 1000+ icons.Why Both Packages:

lucide: Icon data and definitions
lucide-angular: Angular component wrappers

Usage Examples:

Button icons
Menu item icons
Input prefix/suffix icons
Navigation icons

gridstack (Required)

Version Range: ^12.0.0Responsive dashboard grid layout engine.Used By:

MagaryGrid (dashboard grid component)
MagaryGridItem (grid item wrapper)

Features:

Drag-and-drop grid items
Responsive breakpoints
Auto-positioning

Step-by-Step Installation

Install Packages

Run the installation command for your package manager:

pnpm add ng-magary @angular/cdk @angular/animations @atlaskit/pragmatic-drag-and-drop lucide lucide-angular gridstack

This installs ng-magary and all required peer dependencies.

Configure Animations Provider

Enable animations in your application config (app.config.ts or main.ts):

import { ApplicationConfig } from '@angular/core';
import { provideAnimations } from '@angular/platform-browser/animations';

export const appConfig: ApplicationConfig = {
  providers: [
    provideAnimations(), // Required for Magary animations
    // ... other providers
  ],
};

Configure Lucide Icons

Set up Lucide icon library globally:

app.config.ts

import { ApplicationConfig, importProvidersFrom } from '@angular/core';
import { provideAnimations } from '@angular/platform-browser/animations';
import { LucideAngularModule, icons } from 'lucide-angular';

// Helper to convert icon names to kebab-case
const kebabCase = (value: string) => 
  value.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();

// Register all icons in both PascalCase and kebab-case formats
const lucideIcons = Object.entries(icons).reduce(
  (acc, [key, icon]) => {
    acc[key] = icon;
    acc[kebabCase(key)] = icon;
    return acc;
  },
  {} as Record<string, unknown>,
);

export const appConfig: ApplicationConfig = {
  providers: [
    provideAnimations(),
    importProvidersFrom(LucideAngularModule.pick(lucideIcons)),
  ],
};

The kebab-case conversion allows you to use icons with both icon="ChevronDown" and icon="chevron-down" syntax.

Import Tooltip Styles (Optional)

If you’re using MagaryTooltip, import its global styles:

styles.scss

/* Global styles for tooltip overlay */
@use 'ng-magary/styles/tooltip.scss';

Tooltip styles must be imported globally because tooltips are rendered in a global overlay container, outside your component hierarchy.

Verify Installation

Create a test component to verify everything works:

app.component.ts

import { Component } from '@angular/core';
import { MagaryButton } from 'ng-magary';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [MagaryButton],
  template: `
    <magary-button 
      label="Hello Magary!" 
      severity="primary" 
      icon="rocket"
    />
  `,
})
export class AppComponent {}

Run ng serve and you should see a styled button with a rocket icon.

Version Compatibility Matrix

Always check that your Angular version matches the supported ranges.

Angular Version	ng-magary	@angular/cdk	@angular/animations
17.x	✅ 0.0.22+	^17.0.0	^17.0.0
18.x	✅ 0.0.22+	^18.0.0	^18.0.0
19.x	✅ 0.0.22+	^19.0.0	^19.0.0
20.x	✅ 0.0.22+	^20.0.0	^20.0.0
21.x	✅ 0.0.22+	^21.0.0	^21.0.0
16.x or older	❌ Not supported	-	-

Troubleshooting

Peer Dependency Warnings

Issue: npm/pnpm warns about peer dependency mismatches.Solution:

Check your Angular version:
```
ng version
```

Ensure all Angular packages use the same version:

npm list @angular/core @angular/common @angular/cdk @angular/animations

Update mismatched packages:

npm install @angular/cdk@21 @angular/animations@21

Icons Not Displaying

Issue: Icons appear as empty squares or don’t render.Solution:

Verify Lucide module is imported in app.config.ts:

importProvidersFrom(LucideAngularModule.pick(lucideIcons))

Check icon name spelling (case-sensitive):

<!-- ✅ Correct -->
<magary-button icon="home" />
<magary-button icon="ChevronDown" />

<!-- ❌ Wrong -->
<magary-button icon="Home" />  <!-- PascalCase won't work without kebab-case helper -->

Ensure you’re using a valid Lucide icon name from lucide.dev

Animations Not Working

Issue: Components appear/disappear instantly without transitions.Solution:

Add provideAnimations() to your app config:

import { provideAnimations } from '@angular/platform-browser/animations';

export const appConfig: ApplicationConfig = {
  providers: [provideAnimations()],
};

If using SSR/server-side rendering, use provideNoopAnimations() on the server:

import { provideNoopAnimations } from '@angular/platform-browser/animations';

Tooltip Styles Missing

Issue: Tooltips have no background or appear unstyled.Solution:Import tooltip styles in your global styles.scss:

@use 'ng-magary/styles/tooltip.scss';

Make sure this file is referenced in angular.json:

"styles": [
  "src/styles.scss"  // Your global styles file
]

Build Errors with gridstack

Issue: TypeScript or build errors related to gridstack.Solution:

Ensure gridstack is properly installed:
```
npm install gridstack@^12.0.0
```
If you’re not using grid components, gridstack is still required as a peer dependency but won’t affect your bundle size (tree-shaking).

Module Not Found Errors

Issue: Cannot find module 'ng-magary' or similar errors.Solution:

Clear node_modules and reinstall:

rm -rf node_modules package-lock.json
npm install

Restart your dev server:
```
ng serve
```
Check that ng-magary appears in node_modules/:
```
ls node_modules/ng-magary
```

Advanced Configuration

Selective Icon Import

To reduce bundle size, import only the icons you use:

app.config.ts

import { LucideAngularModule, Home, Settings, User } from 'lucide-angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideAnimations(),
    importProvidersFrom(
      LucideAngularModule.pick({ Home, Settings, User })
    ),
  ],
};

This approach requires you to manually import each icon. Use the full icon set approach (from the installation steps) for convenience.

Server-Side Rendering (SSR)

If your app uses Angular Universal or SSR:

app.config.server.ts

import { ApplicationConfig } from '@angular/core';
import { provideNoopAnimations } from '@angular/platform-browser/animations';

export const serverConfig: ApplicationConfig = {
  providers: [
    provideNoopAnimations(), // Use noop animations on server
  ],
};

Standalone vs Module-Based Apps

Standalone (Recommended)
Module-Based (Legacy)

Magary is designed for standalone components. Simply import components in your component’s imports array:

import { Component } from '@angular/core';
import { MagaryButton, MagaryCard } from 'ng-magary';

@Component({
  standalone: true,
  imports: [MagaryButton, MagaryCard],
  // ...
})
export class MyComponent {}

While Magary is standalone-first, you can use it in module-based apps:

import { NgModule } from '@angular/core';
import { MagaryButton, MagaryCard } from 'ng-magary';

@NgModule({
  imports: [
    MagaryButton,  // Standalone components can be imported in NgModules
    MagaryCard,
  ],
  declarations: [MyComponent],
})
export class MyModule {}

Next Steps

Quick Start Guide

Build your first Magary component in 5 minutes

Theming Guide

Customize colors, shadows, and glassmorphism effects

Component Library

Explore all 50+ components with examples

GitHub Issues

Report bugs or request features

Get Started

Components

Services

Guides

Examples

Installation

Installation

Quick Install

Understanding Dependencies

Core Package

Peer Dependencies

Step-by-Step Installation

Version Compatibility Matrix

Troubleshooting

Advanced Configuration

Selective Icon Import

Server-Side Rendering (SSR)

Standalone vs Module-Based Apps

Next Steps

Quick Start Guide

Theming Guide

Component Library

GitHub Issues

Build docs developers (and LLMs) love

Get Started

Components

Services

Guides

Examples

​Installation

​Quick Install

​Understanding Dependencies

​Core Package

​Peer Dependencies

​Step-by-Step Installation

​Version Compatibility Matrix

​Troubleshooting

​Advanced Configuration

​Selective Icon Import

​Server-Side Rendering (SSR)

​Standalone vs Module-Based Apps

​Next Steps

Quick Start Guide

Theming Guide

Component Library

GitHub Issues

Build docs developers (and LLMs) love

Installation

Quick Install

Understanding Dependencies

Core Package

Peer Dependencies

Step-by-Step Installation

Version Compatibility Matrix

Troubleshooting

Advanced Configuration

Selective Icon Import

Server-Side Rendering (SSR)

Standalone vs Module-Based Apps

Next Steps