HotToast for Angular

Hot-toast messages are announced via an aria-live region.

• Default behavior: The polite setting is used by default.
• Customization: You can change this by setting the ariaLive property within your ToastConfig or ToastOptions.

Best Practices for Accessibility:

• Focus Management: Do not move the application focus to the hot-toast element, as this is disruptive. Instead, provide alternative ways (like keyboard shortcuts or menus) to perform actions offered within a toast.
• Actionable Toasts: If a toast contains an action, set autoClose: false. This allows screen-reader users enough time to navigate to the element and activate the action.

To test the interceptor within your running Angular application:

1. Start the test server (npm run sample:http-test-server).
2. Start your Angular app (usually http://localhost:4200).
3. Ensure your application's environment.sampleHttpTestServerUrl is set to the server URL (default is http://localhost:4000).
4. Navigate to the sample page: http://localhost:4200/http-interceptor-sample.

Alternatively, you can trigger an error directly from the browser DevTools console to see if a toast appears:

fetch('http://localhost:4000/api/server-error').catch(() => {});

Testing Header-based logic: To test skipRequest or shouldIgnore logic in your interceptor configuration, call the following endpoint with the X-Skip-Toast: 1 header: GET http://localhost:4000/api/skip-toast-header

HotToast requires base styles to function. You can also import specific themes to change the visual appearance.

1. Add Base Styles

SCSS:

@use '@ngxpert/hot-toast/styles';

CSS (via angular.json):

"styles": [
  "@ngxpert/hot-toast/styles.css"
]

2. Add a Theme (Optional)

Import one theme stylesheet on top of the base styles.

SCSS:

@use '@ngxpert/hot-toast/styles';
@use '@ngxpert/hot-toast/themes/material'; // options: minimal | glassmorphism | ios

CSS (via angular.json):

"styles": [
  "@ngxpert/hot-toast/styles.css",
  "@ngxpert/hot-toast/themes/material.css"
]

Tip: Running ng add @ngxpert/hot-toast handles these imports automatically and prompts you to pick a theme.

Depending on your Angular version, use one of the following methods to install the library.

Angular 19+

Use the Angular CLI to automatically handle installation and styling setup:

ng add @ngxpert/hot-toast

Other Angular Versions

Install via npm or yarn. Note that for older versions, you may need to install @ngneat/overview alongside the library.

npm install @ngneat/overview@7.0.0 @ngxpert/hot-toast
# or
yarn add @ngneat/overview@7.0.0 @ngxpert/hot-toast

If your application uses a manual dark-mode toggle, you can force all themed toasts (Material, Minimal, Glassmorphism, iOS) to render in dark mode by adding the hot-toast-dark-theme class to a parent element, such as the <body> tag.

<body class="hot-toast-dark-theme">
  <!-- All themed toasts inside here will use dark mode -->
</body>

The hot-toast-http-test-server is a small API used to manually verify hotToastHttpInterceptor and provideHotToastHttpInterceptor() configurations, such as status code ignores, toast messages, and headers.

To run the server from the repository root:

npm run sample:http-test-server:install
npm run sample:http-test-server

Alternatively, you can run it directly from the package folder:

npm install
npm start

The server defaults to port 4000. You can change the port by setting the PORT environment variable:

PORT=5000 npm start

To use HotToast, you must provide its configuration in your application's provider list. You can use provideHotToastConfig() for both Standalone and Module-based applications.

Standalone Setup (Angular 14+)

Add provideHotToastConfig() to the providers array in your bootstrapApplication call.

Module Setup

Add provideHotToastConfig() to the providers array in your @NgModule.

import { provideHotToastConfig } from '@ngxpert/hot-toast';

// Standalone
bootstrapApplication(AppComponent, {
  providers: [
    provideHotToastConfig(),
  ],
});

// Module-based
@NgModule({
  providers: [provideHotToastConfig()],
})
class AppModule {}

You can optionally register a functional interceptor to automatically show error toasts when HttpClient requests fail. The interceptor ensures failed requests are still rethrown to your existing subscribe or catchError handlers.

To use it, add hotToastHttpInterceptor to your provideHttpClient call and use provideHotToastHttpInterceptor() to configure rules like ignoreStatuses (e.g., to skip 401 errors).

import { hotToastHttpInterceptor, provideHotToastHttpInterceptor, provideHotToastConfig } from '@ngxpert/hot-toast';
import { provideHttpClient, withFetch, withInterceptors } from '@angular/common/http';

bootstrapApplication(AppComponent, {
  providers: [
    provideHotToastConfig(),
    provideHttpClient(withFetch(), withInterceptors([hotToastHttpInterceptor])),
    provideHotToastHttpInterceptor({
      ignoreStatuses: [401],
    }),
  ],
});

Hot-toast supports several built-in themes. Note that some advanced themes require importing specific SCSS files in your project:

• toast: The default look (no extra import needed).
• snackbar: A dark snackbar variant (included in base styles).
• material: Material Design elevation and typography. Requires: @use '@ngxpert/hot-toast/themes/material'.
• minimal: A borderless, shadowless, clean look. Requires: @use '@ngxpert/hot-toast/themes/minimal'.
• glassmorphism: A frosted-glass effect. Requires: @use '@ngxpert/hot-toast/themes/glassmorphism'.
• ios: An iOS-style pill with blur effect. Requires: @use '@ngxpert/hot-toast/themes/ios'.

In addition to standard ToastOptions, you can configure the following global settings for how toasts are stacked and displayed:

By default, the iOS theme follows system preferences. To force the dark mode appearance regardless of the user's OS settings, apply the .hot-toast-dark-theme class to a parent element, such as the <body> or <html> tag.

<body class="hot-toast-dark-theme">
  <!-- Hot Toast components will now use dark mode iOS styles -->
</body>

You can automatically set up @ngxpert/hot-toast in your Angular project by using the ng add command. This schematic handles adding the necessary dependencies to your package.json and triggers a package installation task followed by a project setup schematic (ng-add-setup-project).

npx ng add @ngxpert/hot-toast