🍞 react-native-turbo-toast

🎯 Why Choose This Library?

🚀 Performance First

• TurboModule architecture (no bridge overhead)
• Native driver animations (60fps)
• Optimized queue operations O(log n)
• < 25KB bundle impact
• < 5ms initialization

🛠️ Developer Experience

• 100% TypeScript with IntelliSense
• Zero configuration required
• Hot reload friendly
• Comprehensive error messages
• Visual debugging tools

📱 Platform Native

• iOS: UIKit integration
• Android: Custom WindowManager
• Web: DOM with touch events
• Consistent API everywhere
• Platform-specific optimizations

📦 Installation

# npm
npm install react-native-turbo-toast

# yarn
yarn add react-native-turbo-toast

# bun
bun add react-native-turbo-toast

# expo
npx expo install react-native-turbo-toast

📱 iOS Setup

cd ios && pod install

🤖 Android

No additional setup required!

🌐 Web

Works out of the box!

🚀 Quick Start

import Toast from 'react-native-turbo-toast'

// 📝 Simple toast
Toast.show('Hello World!')

// ✅ Success toast
Toast.success('Operation completed!')

// ❌ Error toast
Toast.error('Something went wrong')

// ⚠️ Warning toast
Toast.warning('Please check your input')

// ℹ️ Info toast
Toast.info('New update available')

// ⏳ Loading toast
const loadingId = Toast.loading('Processing...')
// Later: Toast.hide(loadingId)

// 🎯 Promise-based toast
await Toast.promise(
  fetchUserData(),
  {
    loading: 'Fetching user data...',
    success: 'User data loaded!',
    error: 'Failed to load user data'
  }
)

🎨 Advanced Features

🎯 Priority Queue System

// Higher priority toasts show first
Toast.show({
  message: '🚨 Critical alert!',
  priority: 10,
  type: 'error'
})

Toast.show({
  message: '📢 Normal notification',
  priority: 5,
  type: 'info'
})

// Manage queue
Toast.pauseQueue()   // ⏸️ Pause processing
Toast.resumeQueue()  // ▶️ Resume processing
const stats = Toast.getQueueStats()  // 📊 Get statistics

🎬 Animation Presets

Toast.show({
  message: '✨ Animated toast!',
  animationPreset: 'bounce',  // fade | slide | bounce | zoom | spring | none
  animationDuration: 300
})

🔘 Multi-Action Support

Toast.show({
  message: '📧 New message received',
  actions: [
    {
      text: 'Reply',
      onPress: () => openReply()
    },
    {
      text: 'Delete',
      style: 'destructive',
      onPress: () => deleteMessage()
    },
    {
      text: 'Later',
      style: 'cancel'  // Won't dismiss toast
    }
  ]
})

📊 Progress Toasts

// Show progress
const id = Toast.showProgress('Uploading...', 0)

// Update progress
for (let i = 0; i <= 100; i += 10) {
  await delay(100)
  Toast.updateProgress(id, i / 100, `Uploading... ${i}%`)
}

Toast.hide(id)

🎨 Custom React Components

import { ToastContainer } from 'react-native-turbo-toast'

// Wrap your app
function App() {
  return (
    <ToastContainer>
      <YourApp />
    </ToastContainer>
  )
}

// Use custom components
Toast.show({
  customView: ({ toast, onDismiss }) => (
    <View style={styles.custom}>
      <Image source={{ uri: 'avatar.png' }} />
      <Text>{toast.message}</Text>
      <Button title="Dismiss" onPress={onDismiss} />
    </View>
  )
})

🪝 React Hooks

import { useToast, useToastQueue } from 'react-native-turbo-toast'

function Component() {
  const toast = useToast()
  const { stats, events } = useToastQueue()

  return (
    <View>
      <Text>📊 Active: {stats.active}</Text>
      <Text>⏳ Queued: {stats.pending}</Text>
      <Button
        title="Show Toast"
        onPress={() => toast.show('Hello!')}
      />
    </View>
  )
}

📱 Group Management

// Group related toasts
Toast.show({
  message: '📬 New email',
  group: 'notifications'
})

Toast.show({
  message: '💬 New chat message',
  group: 'notifications'
})

// Clear entire group
Toast.clearGroup('notifications')

// Find toasts by group
const notifications = Toast.findByGroup('notifications')

💾 Persistence

# Optional peer dependency
npm install @react-native-async-storage/async-storage

Toast.configure({
  persistenceEnabled: true,
  persistenceInterval: 1000  // Auto-save every second
})

📈 Analytics Integration

import { toastAnalytics } from 'react-native-turbo-toast'

// Add your analytics provider
toastAnalytics.addProvider({
  trackEvent: (event) => {
    analytics.track(event.eventType, {
      toastId: event.toastId,
      message: event.message,
      duration: event.duration
    })
  }
})

// Enable tracking
Toast.configure({ analyticsEnabled: true })

⚙️ Configuration

Toast.configure({
  // 🎯 Queue settings
  maxConcurrent: 3,           // Max toasts shown simultaneously
  maxQueueSize: 100,          // Max queued toasts

  // 🎨 Default options
  defaultOptions: {
    position: 'bottom',
    duration: 3000,
    animationPreset: 'slide'
  },

  // 📊 Advanced features
  stackingEnabled: true,       // Visual stacking
  stackingOffset: 10,         // Pixels between stacked toasts
  persistenceEnabled: false,   // Save queue across restarts
  analyticsEnabled: false,     // Track interactions

  // 🔄 Retry logic
  maxRetries: 3,
  retryDelay: 1000
})

📱 Platform Support

| Feature | iOS | Android | Web | Notes | |---------|-----|---------|-----|-------| | 🍞 Basic Toasts | ✅ | ✅ | ✅ | Full support | | 🎨 Custom Styling | ✅ | ✅ | ✅ | Full support | | 🧩 Custom Components | ✅ | ✅ | ✅ | Full support | | 🔘 Multi-Actions | ✅ | ✅ | ✅ | Full support | | 👆 Swipe to Dismiss | ✅ | ⚠️ | ✅ | Android: Tap only* | | 📳 Haptic Feedback | ✅ | ✅ | ✅ | Full support | | 📊 Progress Bars | ✅ | ✅ | ✅ | Full support | | 🎯 Queue Management | ✅ | ✅ | ✅ | Full support | | ✨ Animations | ✅ | ✅ | ✅ | Full support | | 💾 Persistence | ✅ | ✅ | ⚠️ | Web: localStorage** |

* Android uses WindowManager which doesn't support swipe gestures ** Web requires localStorage adapter (not included)

🧪 TypeScript

Full TypeScript support with comprehensive type definitions:

import type { ToastOptions, ToastConfig } from 'react-native-turbo-toast'

const options: ToastOptions = {
  message: '🎉 Typed toast',
  type: 'success',
  position: 'top',
  duration: 3000,
  priority: 5,
  group: 'notifications',
  animationPreset: 'bounce',
  actions: [
    { text: 'OK', onPress: () => {} }
  ]
}

const config: ToastConfig = {
  maxConcurrent: 3,
  stackingEnabled: true,
  defaultOptions: {
    position: 'bottom'
  }
}

📊 Performance Metrics

| Metric | Value | Notes | |--------|-------|-------| | 📦 Bundle Size | < 25KB | Minified + gzipped | | 🧠 Memory Usage | < 1MB | Per active toast | | 🎬 Animations | 60fps | Native driver | | ⚡ Queue Ops | < 1ms | O(log n) complexity | | 🚀 Cold Start | < 5ms | Initial setup | | 📱 Show Toast | < 10ms | Call to display |

🔗 API Reference

Core Methods

| Method | Description | Example | |--------|-------------|---------| | show(options) | Display toast | Toast.show('Hello') | | hide(id?) | Hide toast | Toast.hide() | | hideAll() | Clear all toasts | Toast.hideAll() | | update(id, options) | Update active toast | Toast.update(id, { message: 'Updated' }) | | configure(config) | Set global config | Toast.configure({ maxConcurrent: 5 }) |

Template Methods

| Method | Description | |--------|-------------| | success(message, options?) | ✅ Green success toast | | error(message, options?) | ❌ Red error toast | | warning(message, options?) | ⚠️ Orange warning toast | | info(message, options?) | ℹ️ Blue info toast | | loading(message?, options?) | ⏳ Persistent loading toast | | promise(promise, messages, options?) | 🎯 Promise-based toast |

Queue Management

| Method | Description | |--------|-------------| | getQueueStats() | 📊 Get queue statistics | | pauseQueue() | ⏸️ Pause processing | | resumeQueue() | ▶️ Resume processing | | clearGroup(group) | 🗑️ Clear group toasts | | reorderToast(id, priority) | 🔄 Change priority |

Complete API documentation: API.md

🚀 Examples

Check out the example app for comprehensive usage:

cd example
npm install

# iOS
npm run ios

# Android
npm run android

# Web
npm run web

🤝 Contributing

We love contributions! Please see our Contributing Guide for details.

# Fork and clone
git clone https://github.com/YOUR_USERNAME/react-native-turbo-toast.git

# Install dependencies
npm install

# Run tests
npm test

# Submit PR

📄 License

MIT © Anivar Aravind