Toast

Non-blocking notification messages that appear at the corner of the screen and dismiss automatically. Powered by the @primus/ui-core JS bundle via the global primus.toast() API.

Requires JS bundle

Toast requires the @primus/ui-core JS bundle. Add it once to your app:

• Angular: "scripts": ["node_modules/@primus/ui-core/dist/primus-ui.min.js"] in angular.json
• React: import '@primus/ui-core/dist/primus-ui.min.js' in main.tsx
• HTML: <script type="module" src="https://unpkg.com/@primus/ui-core/dist/primus-ui.min.js"></script>

Preview · Toast variants

Code

HTML · @primus/ui-core

<!-- Ensure the JS bundle is loaded first -->
<script type="module" src="https://unpkg.com/@primus/ui-core/dist/primus-ui.min.js"></script>

<script>
  // Basic info toast
  primus.toast('Syncing data in the background.');

  // With title + variant
  primus.toast('All changes saved.', 'Saved', { variant: 'success' });
  primus.toast('Connection failed.', 'Error', { variant: 'danger' });
  primus.toast('Storage at 90%.', 'Warning', { variant: 'warning' });

  // Persistent (no auto-dismiss)
  primus.toast('Processing your request...', 'Please wait', { duration: 0 });

  // Clear all toasts
  primus.toast.clear();
  primus.toast.clear('bottom-right'); // clear a specific placement
</script>

React

// Import the JS bundle once in main.tsx
import '@primus/ui-core/dist/primus-ui.min.js';

// Declare the global type
declare const primus: {
  toast: (message: string, title?: string, options?: ToastOptions) => void;
};

interface ToastOptions {
  variant?:   'success' | 'danger' | 'warning' | 'info';
  duration?:  number;   // ms — 0 for persistent
  placement?: 'top-left' | 'top-center' | 'top-right'
            | 'bottom-left' | 'bottom-center' | 'bottom-right';
}

// Call from any component or service
function handleSave() {
  try {
    await saveData();
    primus.toast('All changes saved.', 'Saved', { variant: 'success' });
  } catch {
    primus.toast('Failed to save.', 'Error', { variant: 'danger' });
  }
}

// Custom hook (optional)
export function useToast() {
  return {
    success: (msg: string, title = 'Success') =>
      primus.toast(msg, title, { variant: 'success' }),
    error: (msg: string, title = 'Error') =>
      primus.toast(msg, title, { variant: 'danger' }),
    warning: (msg: string) =>
      primus.toast(msg, 'Warning', { variant: 'warning' }),
    info: (msg: string) =>
      primus.toast(msg),
  };
}

Angular

// app.component.ts — add script to angular.json scripts array:
// "scripts": ["node_modules/@primus/ui-core/dist/primus-ui.min.js"]

// toast.service.ts
import { Injectable } from '@angular/core';

declare const primus: {
  toast: (message: string, title?: string, options?: {
    variant?: 'success' | 'danger' | 'warning' | 'info';
    duration?: number;
    placement?: string;
  }) => void;
};

@Injectable({ providedIn: 'root' })
export class ToastService {
  success(message: string, title = 'Success') {
    primus.toast(message, title, { variant: 'success' });
  }
  error(message: string, title = 'Error') {
    primus.toast(message, title, { variant: 'danger' });
  }
  warning(message: string, title = 'Warning') {
    primus.toast(message, title, { variant: 'warning' });
  }
  info(message: string, title?: string) {
    primus.toast(message, title);
  }
}

// any.component.ts
export class TenantComponent {
  constructor(private toast: ToastService) {}

  async onSave() {
    try {
      await this.tenantSvc.save(this.form.value);
      this.toast.success('Tenant saved successfully.');
    } catch (err: any) {
      this.toast.error(err.message);
    }
  }
}

API Reference

primus.toast(message, title?, options?)

Parameter	Type	Default	Description
message	string	required	Toast body text
title	string	—	Bold heading above message
options.variant	'success' | 'danger' | 'warning' | 'info'	'info'	Visual style and icon
options.duration	number	4000	Auto-dismiss delay in ms. 0 = persistent
options.placement	string	'top-right'	Screen position

Placements

Value	Position
top-left	Top left corner
top-center	Top centre
top-right	Top right corner (default)
bottom-left	Bottom left corner
bottom-center	Bottom centre
bottom-right	Bottom right corner

primus.toast.clear(placement?)

Dismiss all visible toasts. Pass a placement string to clear only that stack.

Version history

See the Changelog for version history and breaking changes.