React Native Nitro Timer

High-performance native timer component using React Native Nitro HybridViews for e-commerce applications.

Perfect for apps that need multiple countdown timers with zero bridge traffic and native performance.

🚀 Key Features

• 🔥 Zero Bridge Traffic: Timer updates happen entirely in native code
• ⚡ Native UI Rendering: Direct UILabel/TextView updates, no React re-renders
• 🎯 Multiple Timer Support: 10+ timers per screen with shared native manager
• 🔄 Background Accuracy: Continues running when app is backgrounded
• 🧵 JS Thread Independence: Accurate timing even when JS thread is blocked
• 📱 Production Ready: Battle-tested for e-commerce applications

📊 Performance Comparison

| Metric | JavaScript Timers | Nitro Timer | |--------|------------------|-------------| | Bridge calls/second | 1+ per timer | 0 | | React re-renders | 1 per timer/second | 0 | | Memory usage | Growing | Constant | | Frame drops | Possible | None | | Background accuracy | Limited | Full |

📱 E-commerce Use Cases

• ⚡ Flash sale countdowns on product grids
• 🏷️ Limited time offer banners
• 📦 Shipping cutoff timers
• 🔨 Auction bidding countdowns
• ⏰ Stock urgency indicators

🔧 Installation

npm install react-native-nitro-timer react-native-nitro-modules
# or
yarn add react-native-nitro-timer react-native-nitro-modules

iOS Setup

cd ios && pod install

Android Setup

No additional setup required - auto-linking will handle it.

📖 Quick Start

Basic Timer

import { NitroTimerView } from 'react-native-nitro-timer';

export default function App() {
  const endTime = new Date(Date.now() + 2 * 60 * 60 * 1000).toISOString(); // 2 hours

  return (
    <NitroTimerView
      endTime={endTime}
      format="HH:MM:SS"
      fontSize={24}
      textColor="#000000"
      autoStart={true}
      onExpired={() => console.log('Timer expired!')}
    />
  );
}

E-commerce Flash Sale

<NitroTimerView
  endTime="2024-12-25T15:30:00Z"
  format="Hh Mm Ss"
  fontSize={18}
  textColor="#FF0000"
  criticalColor="#CC0000"
  criticalThreshold={300} // Last 5 minutes
  fontWeight="bold"
  textAlign="center"
  backgroundColor="#FFE6E6"
  cornerRadius={8}
  padding={16}
  onCritical={() => Alert.alert('Hurry!', 'Only 5 minutes left!')}
  onExpired={() => hideFlashSale()}
/>

Product Grid with Multiple Timers

import { ScrollView, View, Text, Image } from 'react-native';
import { NitroTimerView } from 'react-native-nitro-timer';

export default function ProductGrid({ products }) {
  return (
    <ScrollView>
      {products.map(product => (
        <View key={product.id} style={styles.productCard}>
          <Image source={{ uri: product.image }} style={styles.productImage} />
          <Text style={styles.productName}>{product.name}</Text>
          <Text style={styles.productPrice}>${product.price}</Text>

          <NitroTimerView
            endTime={product.saleEndTime}
            format="H:M:S"
            fontSize={12}
            textColor="#333"
            criticalColor="#FF0000"
            criticalThreshold={600} // 10 minutes
            fontWeight="bold"
            textAlign="center"
            backgroundColor="#F0F0F0"
            cornerRadius={4}
            padding={8}
          />
        </View>
      ))}
    </ScrollView>
  );
}

🎛️ Props

Core Timer Config

• endTime: string - ISO 8601 format end time
• autoStart: boolean - Auto-start timer (default: true)
• criticalThreshold: number - Seconds when timer becomes "critical"

Display Format

• format: 'HH:MM:SS' | 'H:M:S' | 'Hh Mm Ss' | 'H hours M minutes'
• showDays: boolean - Show days in countdown
• hideZeroHours: boolean - Hide hours when zero

Styling

• fontSize: number - Text size
• textColor: string - Normal text color
• criticalColor: string - Color when critical
• fontWeight: 'normal' | 'bold'
• textAlign: 'left' | 'center' | 'right'
• backgroundColor?: string - Background color
• cornerRadius?: number - Border radius
• padding?: number - Internal padding

Behavior

• pauseWhenNotVisible: boolean - Pause when off-screen
• continueInBackground: boolean - Keep running in background

Events

• onExpired?: () => void - Called when timer expires
• onCritical?: () => void - Called when entering critical state

🎯 Methods

Access timer methods via ref:

const timerRef = useRef<NitroTimer>(null);

// Timer controls
timerRef.current?.start();
timerRef.current?.pause();
timerRef.current?.resume();
timerRef.current?.reset();
timerRef.current?.addSeconds(60);
timerRef.current?.setEndTime("2024-12-25T15:30:00Z");

// Get current state
const timerData = await timerRef.current?.getCurrentTime();

📊 Performance

Benchmarks

• Bridge Traffic: 0 calls/second during operation (vs 1+ for JS timers)
• Memory Usage: Constant regardless of timer count
• Accuracy: ±50ms precision even under heavy JS load
• Battery: Minimal impact with 10+ concurrent timers

E-commerce Impact

• Smooth scrolling through product grids with multiple timers
• Accurate countdown timers after app backgrounding
• No frame drops during timer updates
• Reduced React re-renders and improved app performance

🏗️ Architecture

iOS Implementation

• Single CADisplayLink driving all timer instances
• Direct UILabel text updates on main thread
• DateComponentsFormatter for time formatting
• Background/foreground app state handling
• Memory-efficient timer registry

Android Implementation

• Single Handler with Runnable for all timers
• Direct TextView updates on UI thread
• Efficient time calculation and formatting
• Activity lifecycle awareness
• Batch updates for multiple timer instances

🔒 Native Features

• Timer Manager: Single native timer drives all instances
• Direct UI Updates: No bridge calls during normal operation
• Background Handling: App state transitions managed natively
• Memory Efficient: Shared timer mechanism across instances
• Thread Safe: All timer operations properly synchronized

📋 Example App

Run the example app to see various timer configurations:

cd example
npm install
npx react-native run-ios
# or
npx react-native run-android

🤝 Contributing

• Development workflow
• Sending a pull request
• Code of conduct

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Built with React Native Nitro modules for maximum performance.

Made with create-react-native-library