🚀 react-native-nitro-toast

Why Nitro Toast?

react-native-nitro-toast is a lightweight, native-powered toast notification library for React Native, built with SwiftUI (iOS) and Jetpack Compose (Android). It is designed for:

• ⚡ 100% Native UI — zero bridge, TurboModule-native
• 🚀 Smooth Animations — powered by SwiftUI & Compose
• 🎯 Simple API — with sensible defaults and full TypeScript support
• 🎨 Highly Customizable — override colors, icons, positions, haptics

⚠️ Looking for full layout customization (e.g. JSX content)?
Consider using a JavaScript-based solution like react-native-toast-message instead.

📸 Preview

🔔 Alert Style (Default)

🍞 Stacked Presentation

https://github.com/user-attachments/assets/a4ba0016-3b17-4b50-9b58-09357eb10047

Check out the stacked presentation guide for more info.

🔥 Native animations with ultra-smooth transitions on both platforms.

✨ Features

• Display modes: alert or stacked
• Predefined Types: success, error, info, warning, default, loading
• Promise-based toasts (loading → success/error)
• Highly Customizable:
  • Position: top / bottom
  • Duration-based or sticky
  • Color overrides (titleColor, messageColor, backgroundColor)
  • Custom icon support (via iconUri)
  • Custom font support (via fontFamily)
• Haptic Feedback Support
• Safe-area aware
• Gesture Dismissal (swipe to dismiss)
• Auto Dismiss Pause when holding

📦 Installation

See the INSTALLATION.md guide for full setup, requirements, and platform instructions.

🔧 Quick Start

Check out the example app for a full working demo.

import { showToast, dismissToast } from 'react-native-nitro-toast';

// Basic usage
showToast('Upload completed!');

// Advanced usage
showToast('Upload completed!', {
  type: 'success',
  position: 'top',
  duration: 3000,
  title: 'Success',
  backgroundColor: '#4CAF50',
  messageColor: '#FFFFFF',
  haptics: true,
});

// Hide title completely
showToast('Just a message, no title', {
  title: '',
  backgroundColor: '#333',
});

// Manual loading toast (useful for loading or sticky toasts)
const id = showToast('Loading...', { type: 'loading' });
// Dismiss the toast when your async work is done
dismissToast(id);

⏳ Promise-based Toasts

import { showToastPromise } from 'react-native-nitro-toast';

// Example: Show a toast for an async upload process
function handleUpload() {
  showToastPromise(
    uploadFile(), // Replace with your async function returning a promise
    {
      loading: 'Uploading your file...',
      success: result => result.message,
      error: error => error instanceof Error ? error.message : 'Upload failed. Please try again.',
    },
    {
      position: 'top',
      haptics: true,
      loading: { title: 'Uploading' },
    }
  );
}

📚 Guides & Documentation

• Custom Icons: Learn how to use react-native-vector-icons or local images.
• Stacked Toasts: See how to manage multiple queued toasts.

🛠 Configuration Options

| Prop | Type | Default | Description | |------------------|------------------------------|-------------|--------------------------------------------| | type | success, error, info, warning, default, loading | 'default' | Predefined visual styles, including loading indicator | | message | string | (required) | Toast message | | title | string | null | Optional title. Pass empty string "" to hide title completely | | fontFamily | string | null | Custom font family (e.g. Rubik, Delius...) | | duration | number (MS) | 4000 | Auto-dismiss duration (0 for sticky/manual) | | position | 'top' | 'bottom' | 'bottom' | Toast position | | presentation | 'stacked' | 'alert' | 'alert' | alert: single toast. stacked: queue multiple toasts. | | haptics | boolean | false | Enable haptic feedback (requires VIBRATE permission on Android) | | iconUri | string (URI) | undefined | Custom icon image URI. | | backgroundColor| string (HEX) | Varies by type | Custom background | | titleColor | string (HEX) | Varies by type | Custom title color (optional) | | messageColor | string (HEX) | Varies by type | Custom message color (optional) | | useOverlay | boolean | true | Apply semi-transparent overlay |

🤝 Contributing & Issues

Contributions are always welcome! If you have an idea, find a bug, or want to help improve the library, please feel free to:

• Create an issue to report bugs or suggest features.
• Open a pull request with your improvements.

👨‍💻 Author

Made with ❤️ by Kiet Huynh

📝 Changelog

See CHANGELOG.md for release notes and version history.

📝 License

MIT