@treditpackage/toast

Headless-ish toast system for React with a context-based API, a flexible viewport component, and configurable styling via CSS variables.

• Framework: React (TypeScript-ready)
• Peer deps: react >=17, react-dom >=17

Installation

npm install @treditpackage/toast
# or
yarn add @treditpackage/toast
# or
pnpm add @treditpackage/toast

Basic usage

1. Wrap your app with ToastProvider.
2. Render ToastViewport once (usually near the root).
3. Use the useToast hook to show toasts.

// src/main.tsx or src/App.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { ToastProvider, ToastViewport } from '@treditpackage/toast';
import '@treditpackage/toast/toast.css';

import { App } from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <ToastProvider>
      <App />
      {/* Place once, typically at root */}
      <ToastViewport />
    </ToastProvider>
  </React.StrictMode>,
);

Then in any component inside the provider:

import { useToast } from '@treditpackage/toast';

export function Example() {
  const { showToast } = useToast();

  const handleClick = () => {
    showToast({
      title: 'Saved successfully',
      message: 'Your changes have been stored.',
      variant: 'success',
      placement: 'top-right',
    });
  };

  return <button onClick={handleClick}>Show toast</button>;
}

Importing styles

The package ships with a default stylesheet. Import it once in your app entry (or any global styles file):

import '@treditpackage/toast/toast.css';

You can override the default theme using CSS variables in your own stylesheet:

:root {
  --color-toast-success-bg: #022c22;
  --color-toast-success-border: #16a34a;
  --color-toast-success-text: #ecfdf5;
  --color-toast-success-icon: #4ade80;

  --color-toast-info-bg: #020617;
  --color-toast-info-border: #0ea5e9;
  --color-toast-info-text: #e5f4ff;
  --color-toast-info-icon: #38bdf8;

  /* ...warning, error, question variables... */
}

API

ToastProvider

import { ToastProvider } from '@treditpackage/toast';

<ToastProvider>
  {/* your app */}
</ToastProvider>;

Wrap your React tree with ToastProvider to make the toast context available. Required for useToast and ToastViewport to work.

useToast

import { useToast } from '@treditpackage/toast';

const { showToast, dismissToast, clearToasts } = useToast();

• showToast(input: ShowToastInput): string: create a new toast and returns its id.
• dismissToast(id: string, reason?, exitAnimation?): programmatically dismiss a toast.
• clearToasts(): remove all toasts.

ShowToastInput (all fields are optional and strongly typed):

• title?: string: toast title (required at runtime unless you set defaults via ToastViewport).
• message?: string: body text.
• variant?: 'info' | 'success' | 'warning' | 'error' | 'question'.
• placement?: 'top-right' | 'top-left' | 'top-center' | 'bottom-right' | 'bottom-left' | 'bottom-center'.
• durationMs?: number: auto-dismiss timeout in ms (default ~3600ms).
• dismissible?: boolean: whether close button / click-to-dismiss is enabled.
• poppable?: boolean: whether clicking the toast should “pop” it.
• stackInsert?: 'front' | 'end': where new toasts appear in the stack.
• appearDelayMs?: number: delay for entrance animation.
• animation_appear?: boolean, animation_cascade?: boolean, exitAnimation?: 'fade' | 'pop'.
• Sizing & shape: width, minHeight, padding, shape ('rounded' | 'square' | 'pill'), borderRadius, titleFontSize, bodyFontSize.
• Actions: actions?: ToastAction[] (see below).
• Colors: colorOverrides?: ToastColorOverrides to override palette per-toast.
• Callbacks: onClick?(toast), onAction?(actionId, toast).

Example with actions:

showToast({
  title: 'Update available',
  message: 'Reload to get the latest version.',
  variant: 'info',
  actions: [
    {
      id: 'reload',
      label: 'Reload',
      tone: 'primary',
      onPress: () => window.location.reload(),
    },
  ],
});

ToastViewport

import { ToastViewport } from '@treditpackage/toast';

function Root() {
  return (
    <ToastProvider>
      <App />
      <ToastViewport />
    </ToastProvider>
  );
}

Primary responsibilities:

• Renders all active toasts using the internal layout and animations.
• Allows you to set default values for toasts shown via showToast while this viewport is mounted.
• Controls placement offsets, max width, z-index, and box-shadow.

Props:

• topOffset?: number | string (default 96)
• rightOffset?: number | string (default 20)
• bottomOffset?: number | string (default 20)
• leftOffset?: number | string (default 20)
• maxStackWidth?: number | string (default 420)
• zIndex?: number (default 2000)
• placement?: ToastPlacement: force a single placement; otherwise all placements are used.
• type?: ToastVariant: default variant for toasts created while this viewport is mounted.
• title?: string, message?: string, durationMs?: number: default values for toasts.
• shadow?: string: custom box-shadow for each toast card.

Example setting defaults per viewport:

<ToastViewport
  placement="bottom-center"
  type="success"
  durationMs={4000}
/>

Any showToast call made while this viewport is mounted will use those defaults unless overridden in the call.

TypeScript support

The package is written in TypeScript and ships with type declarations. All exported types (such as ToastVariant, ToastPlacement, ShowToastInput, ToastAction, etc.) are available:

import type { ShowToastInput, ToastVariant } from '@treditpackage/toast';

Summary

• Install @treditpackage/toast and import @treditpackage/toast/toast.css once.
• Wrap your app with ToastProvider.
• Render a single ToastViewport (configure placement/offsets via props).
• Call useToast().showToast(...) anywhere inside the provider to display toasts.