Installation

Start in 3 minutes

Install the library

Run this command in your terminal, inside your Angular project:

npm install ng-toastly

Add the container

The container is where toasts appear. Add it to your main component:

import { Component } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import { ToastContainerComponent } from 'toastly';

@Component({
  selector: 'app-root',
  imports: [RouterOutlet, ToastContainerComponent],
  template: `
    <router-outlet />
    <toastly-container />
  `,
})
export class AppComponent {}

Optional

Add @import 'toastly/styles/toastly.css'; to your styles.css

@import 'toastly/styles/toastly.css';

Automatic Setup with ng add

The fastest way to add ng-toastly to your project.

What is ng add?

ng add is an official Angular CLI command that allows libraries to automatically configure your project.

ng-toastly uses this feature to save you time and prevent common setup mistakes.

How to Use

Simply run this command in your Angular project:

ng add ng-toastly

What Gets Configured

The schematic automatically:

• ✅ Adds provideToastly() to your app configuration
• ✅ Adds toastly-container to your AppComponent
• ✅ Detects if your project uses standalone or NgModule
• ✅ Avoids duplicating code if already configured
• ✅ Shows clear messages about what was changed

What It Does NOT Do

By design, the schematic does not:

• ❌ Set a specific theme (light/dark)
• ❌ Configure language or i18n
• ❌ Modify your app's styles or layout
• ❌ Add unnecessary dependencies

Why Use a Schematic?

• Reduces setup time — No manual file editing required
• Prevents mistakes — Correct configuration every time
• Improves DX — Better developer experience from the start
• Keeps code clean — Adds only what's necessary

Safety & Best Practices

• 🔒 Idempotent: Running twice won't duplicate anything
• 🔍 Respects structure: Works with your existing setup
• 📝 Clear feedback: Terminal messages explain what changed

Available Options

You can customize the schematic with options:

# Set default position
ng add ng-toastly --position=top-right

# Skip container (add manually)
ng add ng-toastly --skipContainer

Show your first toast!

Use the ToastService in any component to show notifications:

Getting Started

import { Component, inject } from '@angular/core';
import { ToastService } from 'toastly';

@Component({
  selector: 'app-my-component',
  template: `
    <button (click)="showToast()">
      Click me!
    </button>
  `,
})
export class MyComponent {
  // Step 1: Inject the service
  private readonly toastService = inject(ToastService);

  showToast(): void {
    // Step 2: Use service to show a toast
    this.toastService.success('It worked! 🎉');
  }
}

Understanding the code line by line:

Toast Types

Choose a type to preview

toastService.info('Info message');

toastService.success('Success message');

toastService.warning('Warning message');

toastService.danger('Error message');

Available Options

Description

toastService.show({
  // Required
  message: 'Your message here',
  
  // Optional
  title: 'Toast Title',
  type: 'success',        // 'info' | 'success' | 'warning' | 'danger'
  theme: 'dark',          // 'light' | 'dark'
  durationMs: 8000,       // Time in ms
  dismissible: true,     // Show close button
  styleClass: 'my-class',
});

Options

Positioning

Position Demo

Positions

How to change position

<toastly-container position="top-right" />

Action Buttons

Dark theme... pairs well with toasts that have action buttons.

toastService.show({
  type: 'info',
  theme: 'dark',
  title: 'Update Available',
  message: 'Version 4.2 available',
  durationMs: 0, // No auto close
  actions: [
    {
      label: 'Skip',
      variant: 'secondary',
      onClick: () => this.skip(),
    },
    {
      label: 'Install',
      variant: 'primary',
      onClick: () => this.install(),
    },
  ],
});

CSS Variables

CSS variables for everything...

/* Customize global look */
:root {
  --toastly-bg: #ffffff;
  --toastly-success: #16a34a;
}

Custom CSS Classes

For granular control, apply custom CSS classes.

1. Define your class in global styles:

.my-gold-toast {
  /* Override variables or properties */
  --toastly-bg: #ffd700;
  --toastly-text: #000000;
  border: 2px solid #b8860b;
  font-weight: bold;
}

2. Use the class when showing a toast:

this.toastService.show({
  message: 'You won a prize! 🏆',
  styleClass: 'my-gold-toast'
});

Custom Icons

Use your own icons...

How does it work?

Toastly accepts a TemplateRef...

1. Install Lucide Angular

npm install lucide-angular

2. Create a template for the icon

In your component...

<!-- Custom icon template -->
<ng-template #customIcon>
  <!-- Reference to Lucide icons -->
  <i-lucide name="download"></i-lucide>
</ng-template>

Using direct SVG (no library)

If you do not want to install an icon library...

<ng-template #svgIcon>
  <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" ...>
    <path d="..." />
  </svg>
</ng-template>

Different icons for each type

You can create a service...

Themes

Light or Dark...

Comparison

Custom Animations

Toastly animations are designed to be smooth and unobtrusive...

Animation Presets

We provide built-in presets for common use cases:

• animationPreset: 'slide' - Slide (Default)
• animationPreset: 'fade' - Fade
• animationPreset: 'bounce' - Bounce

provideToastly({
  animationPreset: 'bounce', // 'slide' | 'fade' | 'bounce'
  position: 'top-right'
});

Custom Animations via Callback

For full control...

Toastly waits...

provideToastly({
  animation: {
    // Called when toast is created
    enter: (element: HTMLElement) => {
      // Use Web Animations API
      element.animate(
        [
          { transform: 'translateX(100%)', opacity: 0 },
          { transform: 'translateX(0)', opacity: 1 }
        ],
        { duration: 300, easing: 'ease-out', fill: 'forwards' }
      );
    },
    // Called when toast is dismissed
    leave: (element: HTMLElement) => {
      return element.animate(
        [
          { opacity: 1 },
          { opacity: 0, transform: 'scale(0.9)' }
        ],
        { duration: 200, easing: 'ease-in', fill: 'forwards' }
      );
    }
  }
});

Customization with CSS Variables

You can tweak speed and easing using CSS variables:

:root {
  /* Default: 300ms */
  --toastly-animation-duration: 500ms;
  
  /* Default: cubic-bezier(...) */
  --toastly-animation-easing: ease-in-out;
}

Accessibility

Best Practices

• ✅ Keep animations short...
• ✅ Use ease-out...
• ❌ Don't use complex animations...
• ❌ Don't block dismissal...

Global Configuration

Set default values for all toasts in your application.

How to Configure

Use provideToastly() in your application configuration:

import { ApplicationConfig } from '@angular/core';
import { provideToastly } from 'ng-toastly';

export const appConfig: ApplicationConfig = {
  providers: [
    provideToastly({
      position: 'top-right',
      theme: 'dark',
      defaultDurationMs: 3000,
      dismissibleByDefault: true,
      newestOnTop: true,
    }),
  ],
};

Available Options

Manual Configuration (Alternative)

You can also provide configuration directly using the injection token:

import { TOAST_GLOBAL_CONFIG } from 'ng-toastly';

export const appConfig = {
  providers: [
    {
      provide: TOAST_GLOBAL_CONFIG,
      useValue: {
        position: 'top-center',
        theme: 'dark',
      },
    },
  ],
};

Best Practices

Common Errors

Technical Decisions

Why Signals?

We use Angular's Signals API because:

• Performance...
• Simplicity...
• Future...
• Fewer bugs...

Why zero dependencies?

We decided not to use...

• Fewer conflicts...
• Smaller bundle...
• Maintenance...
• Control...

Why "simple" code?

Toastly code is intentionally simple...

• Readability...
• Debugging...
• Learning...
• Maintenance...

"Prefer code..."

Why DestroyRef for timers?

We use DestroyRef...

• Prevents memory leaks
• Avoids errors...
• Modern standard...