react-native-toast-system

Host-aware toasts for React Native apps with screens, modals, and bottom sheets.

• Route toasts to the right UI surface with global and host-scoped APIs.
• Ship faster with Expo-ready setup that stays stable through gestures, keyboard shifts, and nested navigation.
• Handle real app feedback flows with built-in dedupe/grouping and promise-based toasts.

Platform support (current): iOS and Android only. Web is not officially supported yet.

When should I use this?

Use this if

• You need to trigger toasts from both app-wide actions and local surfaces.
• Your app uses modals, bottom sheets, or nested navigation stacks.
• You want a typed toast API without building host routing yourself.

Do not use this if

• You only need a single root-level banner with no surface-specific behavior.
• Your app is web-only today.
• You want a full notification center instead of lightweight toast feedback.

10-second quick example

import { toast, useToast } from "react-native-toast-system";

// Global usage
toast.success("Saved successfully");

// Host usage (for example inside a modal)
const modalToast = useToast("modal");
modalToast.error("Something went wrong");

Why this exists

Most toast libraries assume one root host. Real apps do not.

• Modals often need their own surface so feedback is visible where the user is acting.
• Bottom sheets can clip, overlap, or hide global toasts.
• Nested navigation can make root-only toast placement feel disconnected from the active UI.

Live Expo Demo

Scan the QR to open the in-repo example update.

exp://u.expo.dev/3809a530-4f74-45b2-bb25-7a8a6e8672f4/group/5e489388-b5dc-43b6-b459-3a579239adc3

45-second demo flow

One scenario, six behaviors: root toast, modal toast, bottom-sheet toast, dedupe, promise lifecycle, and keyboard-safe bottom placement.

Caption: Root success, modal error, sheet warning, deduped retries, promise loading-to-success, and keyboard-aware bottom toast in one continuous flow.

• Full script + recording plan: docs/DEMO_HOST_AWARE_FLOW.md

AI and Agent References

• Quick reference: llms.txt
• Full reference: llms-full.txt
• Focused references index: llms/README.md
• Docs page: docs/AI_AGENT_GUIDE.md

Quick Links

• Docs site: https://just69glitch.github.io/react-native-toast-system/
• AI agent guide: docs/AI_AGENT_GUIDE.md
• Demo script: docs/DEMO_HOST_AWARE_FLOW.md
• Decision guide: docs/COMPARISON_POSITIONING.md
• Getting Started: docs/GETTING_STARTED.md
• Templates + grouping onboarding: docs/ONBOARDING_05_TEMPLATES_GROUPING.md
• API Reference: docs/API_REFERENCE.md
• Architecture: docs/ARCHITECTURE.md
• Troubleshooting: docs/TROUBLESHOOTING.md
• Expo example notes: example/README.md

📦 Installation

pnpm add react-native-toast-system

Peer dependencies (install if your app does not already have them):

pnpm add react-native-gesture-handler react-native-reanimated react-native-safe-area-context react-native-svg react-native-worklets
pnpm add react-native-screens

react-native-screens is optional and mainly needed for RN Screens overlay scenarios.

✅ Runtime Setup Checklist

1. Enable Reanimated Babel plugin.
2. Wrap app root with GestureHandlerRootView.
3. Wrap app root with SafeAreaProvider.
4. Mount ToastProvider above all toast callers.
5. Mount at least one host (ToastViewport or ToastHost).
6. For native surfaces (for example React Native Modal), wrap with ToastNativeSurfaceBoundary when gesture activation needs a dedicated root.

⚡ Quick Start

Quick start examples target native apps (iOS/Android).

import React from "react";
import { Button, View } from "react-native";
import { ToastProvider, ToastViewport, toast, useToast } from "react-native-toast-system";

function DemoScreen() {
  const localToast = useToast();

  return (
    <View>
      <Button
        title="Global toast"
        onPress={() => toast.success({ title: "Saved", description: "Changes persisted." })}
      />
      <Button
        title="Hook toast"
        onPress={() => localToast.show({ title: "Welcome", description: "Hello from useToast()." })}
      />
    </View>
  );
}

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

🧩 API Surface At A Glance

• ToastProvider: owns store/runtime and binds global API
• ToastViewport / ToastHost: renders host stacks
• toast: global controller facade
• useToast(hostId?): host-scoped controller hook
• createToastSystem(...): typed system helper for templates

Import Paths

Root import remains fully supported:

import { ToastProvider, ToastViewport, toast, useToast } from "react-native-toast-system";

Optional subpath imports are also available:

import { ToastProvider } from "react-native-toast-system/providers";
import { ToastHost, ToastViewport } from "react-native-toast-system/components";
import { useToast } from "react-native-toast-system/hooks";
import { toast } from "react-native-toast-system/utils";

🧪 Expo Playground (In-Repo)

From repository root:

pnpm run example:install
pnpm run example:start
pnpm run example:validate

Optional targets:

pnpm run example:android
pnpm run example:ios
pnpm run example:web

🛠️ Development Commands

pnpm install
pnpm run lint
pnpm run test
pnpm run build
pnpm run pack:dry-run

Docs commands:

pnpm run docs:install
pnpm run docs:start
pnpm run docs:build
pnpm run docs:serve
pnpm run docs:version -- --help

Release readiness checks:

pnpm run validate:release

🧱 Compatibility

• Node: >=18
• React Native: see peerDependencies in package.json
• Expo: validated via the in-repo example/ app

🔍 Validation Philosophy

This project separates automated and manual confidence:

• Automated: lint, typecheck, tests, build, pack dry-run, example validation, docs validation
• Manual: modal/sheet parity, gesture interactions, keyboard overlap, navigation persistence, and full RTL behavior validation after app restart

🏛️ Governance

• Contributing: CONTRIBUTING.md
• Code of Conduct: CODE_OF_CONDUCT.md
• Security Policy: SECURITY.md
• Support Policy: SUPPORT.md
• Versioning Policy: VERSIONING.md
• Release Process: RELEASING.md
• Changelog: CHANGELOG.md

📄 License

MIT