@lookworld4/react-smart-toast
v1.0.0
Published
A zero-config, imperative toast notification system.
Readme
@lookworld4/react-smart-toast
Imperative toast notifications for React. Mount <Toaster /> once, call toast() from any module—no providers or context setup.
Features
- Zero configuration: one component, one import for the API
- TypeScript-first with exported types
- ESM and CommonJS builds (
exportsfield) - React is a peer dependency (not bundled—uses your app’s React)
- No stylesheet to import: layout/colors use inline styles; enter/leave motion uses
@keyframesinjected intodocument.headwhen<Toaster />mounts (keyframes cannot be expressed as inline styles)
Installation
npm install @lookworld4/react-smart-toastPeer dependencies: react and react-dom (≥ 16.8; hooks required).
pnpm add @lookworld4/react-smart-toast
yarn add @lookworld4/react-smart-toastQuick start
1. Render the toaster (e.g. root layout or App):
import { Toaster } from '@lookworld4/react-smart-toast';
export function App() {
return (
<>
{/* your tree */}
<Toaster />
</>
);
}2. Show toasts from event handlers, loaders, or utilities:
import { toast } from '@lookworld4/react-smart-toast';
toast('Something happened');
toast.success('Saved');
toast.error('Request failed');
toast.info('Reminder');
// Stays on screen until the user closes it
toast('Important', { duration: 0 });
// Custom auto-dismiss (milliseconds; default is 3000)
toast('Quick note', { duration: 1500 });
toast.error('Oops', 5000); // shorthand on helpers: second arg is durationAPI
<Toaster />
Renders the stack of toasts (bottom-right). Include one instance in your app.
Motion. On mount, the toaster inserts a singleton <style id="react-smart-toast-keyframes"> into <head> with slide-in (appear) and slide-out (dismiss) keyframes. Toasts animate in when shown and animate out before they are removed (including auto-dismiss after duration). The tag is removed when all <Toaster /> instances have unmounted (ref-counted, so Strict Mode/dev remount behaves correctly).
Accessibility. prefers-reduced-motion: reduce collapses animation duration so exits still complete cleanly without a long sliding effect.
Advanced note: each toast surface also uses the class react-smart-toast-item for that media query—you can scope overrides in your own CSS if needed.
toast(message, options?)
| Argument | Type | Description |
|----------|------|--------------|
| message | string | Text shown in the toast |
| options | ToastOptions | Optional |
ToastOptions:
type?: 'success' \| 'error' \| 'info'— default'info'duration?: number— auto-dismiss after this many ms; default3000. Use0for no auto-dismiss.
Shorthand methods
toast.success(message, duration?);
toast.error(message, duration?);
toast.info(message, duration?);The optional second argument sets duration only (same as passing { duration }).
Exported types
import type { Toast, ToastAPI, ToastOptions, ToastType } from '@lookworld4/react-smart-toast';ToastAPI— type of thetoastobject (callable +success/error/info)Toast— shape of a toast in UI state (includes optionalexitingwhile the slide-out animation plays; not set when you calltoast())ToastType—'success' | 'error' | 'info'
Development
npm install
npm run build # outputs dist/ (CJS, ESM, .d.ts)
npm run dev # tsup watch modeReact is external in the build; consumers must install React themselves.
License
MIT